MSX Game Library - User contributions [en]

Roadmap

2026-05-01T20:51:09Z

Aoineko: /* Build tool */

This is not really a '''Roadmap''' since I can't guarantee any delivery date, but here are the new features planned as of 2025/01/05.

⏳: work in progress features

== Audio ==
* Add support for new audio format:
** [https://github.com/cornelisser/TriloTracker-Re-player TriloTracker FM] replayer (and update of the new SCC replayer).
** [http://www.xl2s.tk/ Realfun 3] replayer.
** [https://hg.sr.ht/~grauw/re-play Re-Play] replayer (from Grauw).
** [https://github.com/artrag/voicenc_scc Voice synthesis on the ISR] replayer (from ARTRAG).
** [https://www.msx.org/wiki/Moonblaster Moonblaster] replayer.
** [https://doc1oo.github.io/LovelyComposerDocs/en/index.html Lovely Composer] [https://github.com/aburi6800/msx-PSGSoundDriver replayer].
** [https://msx.org/news/software/en/adx-player-ver-40-by-mstz80ax ADX replayer].
** KSS replayer.
** MGSP2 replayer.
** MML replayer.
** MIDI replayer (through PSG, MSX-Music and MSX-Audio).
* Add support for new chip:
** ⏳ MoonSound (OPL4) audio chip.
*** Play sound effect using PCM (?)

== Display ==
* Add replayer for [http://msxbanzai.tni.nl/dev/software.html Animecha] data and/or for an original 2D animation format.
* Add video replayer(s) ([https://nazo.main.jp/prog/retropc/acmsxs3.html Easy SCREEN3 Animation Converter]).
* Add bitmap scrolling feature to {{MOD|scroll}} module.
* Add bitmap sprite upscsaler (cf. [https://www.youtube.com/watch?v=9ieE_HG3Bvs NOP]).
* ⏳ Add 3D module (generic 3d data format, transformation and rendering).
* ⏳ Add Raycaster module (using DDA).
* ⏳ Add Movie module (rewrite MGLV exporter from MSXimg and update MSX replayer)
* Add support for [https://msx.org/forum/msx-talk/general-discussion/undocumented-screen-mode-32x212 32x212 screen mode].
* Add pseudo-bitmap support for Print module for tile-based screen mode and sprite (draw on consecutive 16x16).
* Add loader for more common MSX picture formats (SCx, MIF, PCX, BMP, etc.).
* Add support for Yamaha V9938/58 copy commands.
* Add support for Yamaha V9990 copy commands.
** Improve V9990 sample to allow testing of all color mode.
* Add support for [https://github.com/hra1129/TangCartMSX/tree/main/RTL/tangnano20k_vdp_cartridge_rev2_step1/src/th9958/manual V9968 cartridge].
* Add support for 1-color-per-line MSX feature in Pawn module.

== Misc. ==
* Add support for SRAM cartridge: Game Master 2.
* ⏳ Add support for Network cartridge (Gr8net, DenYoNet & Obsonet).
* Add support for Network cable ([https://www.msx.org/wiki/Konami_JE-700 Konami JE-700] & [https://map.grauw.nl/resources/joynet/ JoyNet]).
* Add support for MSX turbo R specific features.
** Add support for R800 assembler (SDCC now support R800 natively).
* Compress
** Add support for ZX0 unpacker to VRAM
** Add support for LZ48 unpacker to <s>RAM and</s> VRAM [https://github.com/EdouardBERGE/rasm/blob/master/decrunch/lz48decrunch_v006b.asm ][https://github.com/uniabis/z80depacker/blob/master/lz48decrunch_v006_180_speed.asm ]
* Improve Game module with an option to force 50 Hz main loop update on all machines
* Add support for variable-width fonts.

== [[Build tool]] ==
* ⏳ Add native support for SDCC 4.5.0 ''(done but waiting for SDCC fix release)''
* Add an option to compile the source files in parallel.
* Add IPS generator (to create a Patch for a given binary).
* Add build option to convert 16 KB ROM-mapper to RAM segment switch and RAM loader.
* Use SDCC's <tt>-M</tt> option to generate file dependency list and allow skip old file option to check all depedecies (Make ''like'').
* Generate [https://sysadminmosaic.ru/en/msx/carnivore2/specification?redirect=1#rcp_file_format RCP file].

== Optimization ==
''Optimize, optimize and optimize!''
* Rewrite update function in assembler for {{MOD|game_pawn}} and {{MOD|scroll}} modules.
* Create optional fast copy/fill/read functions using unrolled outi/ini for {{MOD|vdp}} module (for supported screen mode).
* Add assembler optimization option to the Build tool (using SDCC peep-hole and/or MDL).
* Continue to set the <tt>__preserves_regs</tt> directive for all remaining assembly functions to help the compiler optimize register usage. ''(already done for VDP and V9990 modules)''
* Add [https://www.msxcomputermagazine.nl/mccw/92/Multiplication/en.html fast multiplication function] ([https://msx.org/forum/development/msx-development/fastest-possible-multiplication-routine?page=6])

Want to contribute to MSXgl? Check [[Contribute|this article]].

Roadmap

2026-05-01T20:50:39Z

Aoineko: /* Display */

This is not really a '''Roadmap''' since I can't guarantee any delivery date, but here are the new features planned as of 2025/01/05.

⏳: work in progress features

== Audio ==
* Add support for new audio format:
** [https://github.com/cornelisser/TriloTracker-Re-player TriloTracker FM] replayer (and update of the new SCC replayer).
** [http://www.xl2s.tk/ Realfun 3] replayer.
** [https://hg.sr.ht/~grauw/re-play Re-Play] replayer (from Grauw).
** [https://github.com/artrag/voicenc_scc Voice synthesis on the ISR] replayer (from ARTRAG).
** [https://www.msx.org/wiki/Moonblaster Moonblaster] replayer.
** [https://doc1oo.github.io/LovelyComposerDocs/en/index.html Lovely Composer] [https://github.com/aburi6800/msx-PSGSoundDriver replayer].
** [https://msx.org/news/software/en/adx-player-ver-40-by-mstz80ax ADX replayer].
** KSS replayer.
** MGSP2 replayer.
** MML replayer.
** MIDI replayer (through PSG, MSX-Music and MSX-Audio).
* Add support for new chip:
** ⏳ MoonSound (OPL4) audio chip.
*** Play sound effect using PCM (?)

== Display ==
* Add replayer for [http://msxbanzai.tni.nl/dev/software.html Animecha] data and/or for an original 2D animation format.
* Add video replayer(s) ([https://nazo.main.jp/prog/retropc/acmsxs3.html Easy SCREEN3 Animation Converter]).
* Add bitmap scrolling feature to {{MOD|scroll}} module.
* Add bitmap sprite upscsaler (cf. [https://www.youtube.com/watch?v=9ieE_HG3Bvs NOP]).
* ⏳ Add 3D module (generic 3d data format, transformation and rendering).
* ⏳ Add Raycaster module (using DDA).
* ⏳ Add Movie module (rewrite MGLV exporter from MSXimg and update MSX replayer)
* Add support for [https://msx.org/forum/msx-talk/general-discussion/undocumented-screen-mode-32x212 32x212 screen mode].
* Add pseudo-bitmap support for Print module for tile-based screen mode and sprite (draw on consecutive 16x16).
* Add loader for more common MSX picture formats (SCx, MIF, PCX, BMP, etc.).
* Add support for Yamaha V9938/58 copy commands.
* Add support for Yamaha V9990 copy commands.
** Improve V9990 sample to allow testing of all color mode.
* Add support for [https://github.com/hra1129/TangCartMSX/tree/main/RTL/tangnano20k_vdp_cartridge_rev2_step1/src/th9958/manual V9968 cartridge].
* Add support for 1-color-per-line MSX feature in Pawn module.

== Misc. ==
* Add support for SRAM cartridge: Game Master 2.
* ⏳ Add support for Network cartridge (Gr8net, DenYoNet & Obsonet).
* Add support for Network cable ([https://www.msx.org/wiki/Konami_JE-700 Konami JE-700] & [https://map.grauw.nl/resources/joynet/ JoyNet]).
* Add support for MSX turbo R specific features.
** Add support for R800 assembler (SDCC now support R800 natively).
* Compress
** Add support for ZX0 unpacker to VRAM
** Add support for LZ48 unpacker to <s>RAM and</s> VRAM [https://github.com/EdouardBERGE/rasm/blob/master/decrunch/lz48decrunch_v006b.asm ][https://github.com/uniabis/z80depacker/blob/master/lz48decrunch_v006_180_speed.asm ]
* Improve Game module with an option to force 50 Hz main loop update on all machines
* Add support for variable-width fonts.

== [[Build tool]] ==
* ⏳ Add native support for SDCC 4.5.0 ''(done but waiting for SDCC fix release)''
* Add an option to compile the source files in parallel.
* Add IPS generator (to create a Patch for a given binary).
* Add build option to convert 16 KB ROM-mapper to RAM segment switch and RAM loader.
* Use SDCC's <tt>-M</tt> option to generate file dependency list and allow skip old file option to check all depedecies (Make ''like'').
* Generate [https://sysadminmosaic.ru/en/msx/carnivore2/specification?redirect=1#rcp_file_format RCP file].
* Add option in MSXhex to display occupation of each 16K page for plain ROM (as for mapped ROM segments)

== Optimization ==
''Optimize, optimize and optimize!''
* Rewrite update function in assembler for {{MOD|game_pawn}} and {{MOD|scroll}} modules.
* Create optional fast copy/fill/read functions using unrolled outi/ini for {{MOD|vdp}} module (for supported screen mode).
* Add assembler optimization option to the Build tool (using SDCC peep-hole and/or MDL).
* Continue to set the <tt>__preserves_regs</tt> directive for all remaining assembly functions to help the compiler optimize register usage. ''(already done for VDP and V9990 modules)''
* Add [https://www.msxcomputermagazine.nl/mccw/92/Multiplication/en.html fast multiplication function] ([https://msx.org/forum/development/msx-development/fastest-possible-multiplication-routine?page=6])

Want to contribute to MSXgl? Check [[Contribute|this article]].

Roadmap

2026-05-01T16:56:08Z

Aoineko:

This is not really a '''Roadmap''' since I can't guarantee any delivery date, but here are the new features planned as of 2025/01/05.

⏳: work in progress features

== Audio ==
* Add support for new audio format:
** [https://github.com/cornelisser/TriloTracker-Re-player TriloTracker FM] replayer (and update of the new SCC replayer).
** [http://www.xl2s.tk/ Realfun 3] replayer.
** [https://hg.sr.ht/~grauw/re-play Re-Play] replayer (from Grauw).
** [https://github.com/artrag/voicenc_scc Voice synthesis on the ISR] replayer (from ARTRAG).
** [https://www.msx.org/wiki/Moonblaster Moonblaster] replayer.
** [https://doc1oo.github.io/LovelyComposerDocs/en/index.html Lovely Composer] [https://github.com/aburi6800/msx-PSGSoundDriver replayer].
** [https://msx.org/news/software/en/adx-player-ver-40-by-mstz80ax ADX replayer].
** KSS replayer.
** MGSP2 replayer.
** MML replayer.
** MIDI replayer (through PSG, MSX-Music and MSX-Audio).
* Add support for new chip:
** ⏳ MoonSound (OPL4) audio chip.
*** Play sound effect using PCM (?)

== Display ==
* Add replayer for [http://msxbanzai.tni.nl/dev/software.html Animecha] data and/or for an original 2D animation format.
* Add video replayer(s) ([https://nazo.main.jp/prog/retropc/acmsxs3.html Easy SCREEN3 Animation Converter]).
* Add bitmap scrolling feature to {{MOD|scroll}} module.
* Add bitmap sprite upscsaler (cf. [https://www.youtube.com/watch?v=9ieE_HG3Bvs NOP]).
* ⏳ Add 3D module (generic 3d data format, transformation and rendering).
* ⏳ Add Raycaster module (using DDA).
* ⏳ add Movie module (rewrite MGLV exporter from MSXimg and update MSX replayer)
* Add support for [https://msx.org/forum/msx-talk/general-discussion/undocumented-screen-mode-32x212 32x212 screen mode].
* Add pseudo-bitmap support for Print module for tile-based screen mode and sprite (draw on consecutive 16x16).
* Add loader for more common MSX picture formats (SCx, MIF, PCX, BMP, etc.).
* Add support for Yamaha V9938/58 copy commands.
* Add support for Yamaha V9990 copy commands.
** Improve V9990 sample to allow testing of all color mode.
* Add support for [https://github.com/hra1129/TangCartMSX/tree/main/RTL/tangnano20k_vdp_cartridge_rev2_step1/src/th9958/manual V9968 cartridge].
* Add support for 1-color-per-line MSX feature in Pawn module.

== Misc. ==
* Add support for SRAM cartridge: Game Master 2.
* ⏳ Add support for Network cartridge (Gr8net, DenYoNet & Obsonet).
* Add support for Network cable ([https://www.msx.org/wiki/Konami_JE-700 Konami JE-700] & [https://map.grauw.nl/resources/joynet/ JoyNet]).
* Add support for MSX turbo R specific features.
** Add support for R800 assembler (SDCC now support R800 natively).
* Compress
** Add support for ZX0 unpacker to VRAM
** Add support for LZ48 unpacker to <s>RAM and</s> VRAM [https://github.com/EdouardBERGE/rasm/blob/master/decrunch/lz48decrunch_v006b.asm ][https://github.com/uniabis/z80depacker/blob/master/lz48decrunch_v006_180_speed.asm ]
* Improve Game module with an option to force 50 Hz main loop update on all machines
* Add support for variable-width fonts.

== [[Build tool]] ==
* ⏳ Add native support for SDCC 4.5.0 ''(done but waiting for SDCC fix release)''
* Add an option to compile the source files in parallel.
* Add IPS generator (to create a Patch for a given binary).
* Add build option to convert 16 KB ROM-mapper to RAM segment switch and RAM loader.
* Use SDCC's <tt>-M</tt> option to generate file dependency list and allow skip old file option to check all depedecies (Make ''like'').
* Generate [https://sysadminmosaic.ru/en/msx/carnivore2/specification?redirect=1#rcp_file_format RCP file].
* Add option in MSXhex to display occupation of each 16K page for plain ROM (as for mapped ROM segments)

== Optimization ==
''Optimize, optimize and optimize!''
* Rewrite update function in assembler for {{MOD|game_pawn}} and {{MOD|scroll}} modules.
* Create optional fast copy/fill/read functions using unrolled outi/ini for {{MOD|vdp}} module (for supported screen mode).
* Add assembler optimization option to the Build tool (using SDCC peep-hole and/or MDL).
* Continue to set the <tt>__preserves_regs</tt> directive for all remaining assembly functions to help the compiler optimize register usage. ''(already done for VDP and V9990 modules)''
* Add [https://www.msxcomputermagazine.nl/mccw/92/Multiplication/en.html fast multiplication function] ([https://msx.org/forum/development/msx-development/fastest-possible-multiplication-routine?page=6])

Want to contribute to MSXgl? Check [[Contribute|this article]].

Roadmap

2026-05-01T14:25:57Z

Aoineko: /* Display */

This is not really a '''Roadmap''' since I can't guarantee any delivery date, but here are the new features planned as of 2025/01/05.

⏳: work in progress features

== Audio ==
* Add support for new audio format:
** [https://github.com/cornelisser/TriloTracker-Re-player TriloTracker FM] replayer (and update of the new SCC replayer).
** [http://www.xl2s.tk/ Realfun 3] replayer.
** [https://hg.sr.ht/~grauw/re-play Re-Play] replayer (from Grauw).
** [https://github.com/artrag/voicenc_scc Voice synthesis on the ISR] replayer (from ARTRAG).
** [https://www.msx.org/wiki/Moonblaster Moonblaster] replayer.
** [https://doc1oo.github.io/LovelyComposerDocs/en/index.html Lovely Composer] [https://github.com/aburi6800/msx-PSGSoundDriver replayer].
** [https://msx.org/news/software/en/adx-player-ver-40-by-mstz80ax ADX replayer].
** KSS replayer.
** MGSP2 replayer.
** MML replayer.
** MIDI replayer (through PSG, MSX-Music and MSX-Audio).
* Add support for new chip:
** MoonSound (OPL4) audio chip.
*** Play sound effect using PCM (?)

== Display ==
* Add replayer for [http://msxbanzai.tni.nl/dev/software.html Animecha] data and/or for an original 2D animation format.
* Add video replayer(s) ([https://nazo.main.jp/prog/retropc/acmsxs3.html Easy SCREEN3 Animation Converter]).
* Add bitmap scrolling feature to {{MOD|scroll}} module.
* Add bitmap sprite upscsaler (cf. [https://www.youtube.com/watch?v=9ieE_HG3Bvs NOP]).
* ⏳ Add 3D module (generic 3d data format, transformation and rendering).
* ⏳ Add Raycaster module (using DDA).
* ⏳ add Movie module (rewrite MGLV exporter from MSXimg and update MSX replayer)
* Add support for [https://msx.org/forum/msx-talk/general-discussion/undocumented-screen-mode-32x212 32x212 screen mode].
* Add pseudo-bitmap support for Print module for tile-based screen mode and sprite (draw on consecutive 16x16).
* Add loader for more common MSX picture formats (SCx, MIF, PCX, BMP, etc.).
* Add support for Yamaha V9938/58 copy commands.
* Add support for Yamaha V9990 copy commands.
** Improve V9990 sample to allow testing of all color mode.
* Add support for [https://github.com/hra1129/TangCartMSX/tree/main/RTL/tangnano20k_vdp_cartridge_rev2_step1/src/th9958/manual V9968 cartridge].
* Add support for 1-color-per-line MSX feature in Pawn module.

== Misc. ==
* Add support for SRAM cartridge: Game Master 2.
* Add support for Network cartridge (Gr8net, DenYoNet & Obsonet).
* Add support for Network cable ([https://www.msx.org/wiki/Konami_JE-700 Konami JE-700] & [https://map.grauw.nl/resources/joynet/ JoyNet]).
* Add support for MSX turbo R specific features.
** Add support for R800 assembler (SDCC now support R800 natively).
* Compress
** Add support for ZX0 unpacker to VRAM
** Add support for LZ48 unpacker to <s>RAM and</s> VRAM [https://github.com/EdouardBERGE/rasm/blob/master/decrunch/lz48decrunch_v006b.asm ][https://github.com/uniabis/z80depacker/blob/master/lz48decrunch_v006_180_speed.asm ]
* Improve Game module with an option to force 50 Hz main loop update on all machines
* Add support for variable-width fonts.

== [[Build tool]] ==
* ⏳ Add native support for SDCC 4.5.0 ''(done but waiting for SDCC fix release)''
* Add an option to compile the source files in parallel.
* Add IPS generator (to create a Patch for a given binary).
* Add build option to convert 16 KB ROM-mapper to RAM segment switch and RAM loader.
* Use SDCC's <tt>-M</tt> option to generate file dependency list and allow skip old file option to check all depedecies (Make ''like'').
* Generate [https://sysadminmosaic.ru/en/msx/carnivore2/specification?redirect=1#rcp_file_format RCP file].
* Add option in MSXhex to display occupation of each 16K page for plain ROM (as for mapped ROM segments)

== Optimization ==
''Optimize, optimize and optimize!''
* Rewrite update function in assembler for {{MOD|game_pawn}} and {{MOD|scroll}} modules.
* Create optional fast copy/fill/read functions using unrolled outi/ini for {{MOD|vdp}} module (for supported screen mode).
* Add assembler optimization option to the Build tool (using SDCC peep-hole and/or MDL).
* Continue to set the <tt>__preserves_regs</tt> directive for all remaining assembly functions to help the compiler optimize register usage. ''(already done for VDP and V9990 modules)''
* Add [https://www.msxcomputermagazine.nl/mccw/92/Multiplication/en.html fast multiplication function] ([https://msx.org/forum/development/msx-development/fastest-possible-multiplication-routine?page=6])

Want to contribute to MSXgl? Check [[Contribute|this article]].

Build tool/BIOSReleaseEvent

2026-05-01T09:52:19Z

Aoineko:

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switched out from page 0. It allows you to have an initialization code that runs while the BIOS is still accessible at page 0. For example, to detect the presence of an MSX-Music device using the BIOS routines for cross-slot reading.

This applies to [[target]] formats that place the '''ROM on page 0''' (ROM_48K_ISR, ROM_64K_ISR, ROM_NEO8, and ROM_NEO16), as well as ROM formats that place '''RAM on page 0''' (via the [[Build_tool/InstallRAMISR|InstallRAMISR]] option).

== Usage ==
To use this option, you must provide a function that will be called by the boot process just before the BIOS is removed from page 0 (to make room for the cartridge or memory).

Function prototype:
<syntaxhighlight lang="c">void BIOS_OnRelease();</syntaxhighlight>

== Call context ==

You must be fully aware of the program's initialization context at the time the BIOS_OnRelease callback function is executed. This context depends on the type of target format.

=== ROM in page 0 ===
* Only page 1 of memory space points to the program in ROM
* The mapper has not yet been initialized;
** the selected segments are those selected by default by the hardware at the physical level (see https://www.msx.org/wiki/MegaROM_Mappers);
** mapper initialization will take place immediately after the return from the BIOS_OnRelease function and will overwrite any changes made in the callback;
* The global variables have not been initialized yet (so you can't use those variables because their value is undefined and any change in the callback will be overwrite later during the boot process)
* The <tt>main()</tt> function has not yet been called (so no program-specific initialization has taken place yet)

=== RAM in page 0 ===
* Pages 1 and 2 of memory point to the program in ROM
* The mapper has not yet been initialized;
** the selected segments are those selected by default by the hardware at the physical level (see https://www.msx.org/wiki/MegaROM_Mappers);
** mapper initialization will take place immediately after the return from the BIOS_OnRelease function and will overwrite any changes made in the callback;
* The global variables have not been initialized yet (so you can't use those variables because their value is undefined and any change in the callback will be overwrite later during the boot process)
* The <tt>main()</tt> function has not yet been called (so no program-specific initialization has taken place yet)

=== Notes ===
You must therefore ensure that the code you call within the callback function only calls functions that are visible to the Z80 in the given context:
* Within the first 16 KB for Konami, ASCII-16, and NEO-16 mappers, and plain-ROM.
* Within the first 8 KB for ASCII-8 and NEO-8 mappers.

As a reminder, the order of the module array (<tt>LibModules</tt>) in your program determines the location of each module in the final binary.

For example, if you want to call the MSX-Music detection function from the BIOS_OnRelease() callback, placing the <tt>msx-music</tt> module first in the list ensures that it appears at the beginning of the ROM.
<syntaxhighlight lang="c">
bool g_UseFM; // Used in BIOS_OnRelease (can't be initalized here)

//-----------------------------------------------------------------------------
// Event called before BIOS is released
void BIOS_OnRelease()
{
g_UseFM = (MSXMusic_Initialize() != MSXMUSIC_NOTFOUND);
}
</syntaxhighlight>

Build tool/BIOSReleaseEvent

2026-04-26T09:25:33Z

Aoineko:

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switched out from page 0. It allows you to have an initialization code that runs while the BIOS is still accessible at page 0. For example, to detect the presence of an MSX-Music device using the BIOS routines for cross-slot reading.

This applies to [[target]] formats that place the '''ROM on page 0''' (ROM_48K_ISR, ROM_64K_ISR, ROM_NEO8, and ROM_NEO16), as well as ROM formats that place '''RAM on page 0''' (via the [[Build_tool/InstallRAMISR|InstallRAMISR]] option).

== Usage ==
To use this option, you must provide a function that will be called by the boot process just before the BIOS is removed from page 0 (to make room for the cartridge or memory).

Function prototype:
<syntaxhighlight lang="c">void BIOS_OnRelease();</syntaxhighlight>

== Call context ==

You must be fully aware of the program's initialization context at the time the BIOS_OnRelease callback function is executed. This context depends on the type of target format.

=== ROM in page 0 ===
* Only page 1 of memory space points to the program in ROM
* The mapper has not yet been initialized;
** the selected segments are those selected by default by the hardware at the physical level (see https://www.msx.org/wiki/MegaROM_Mappers);
** mapper initialization will take place immediately after the return from the BIOS_OnRelease function and will overwrite any changes made in the callback;
* The global variables have not been initialized yet (so you can't use those variables because their value is undefined and any change in the callback will be overwrite later during the boot process)
* The <tt>main()</tt> function has not yet been called (so no program-specific initialization has taken place yet)

=== RAM in page 0 ===
* Pages 1 and 2 of memory point to the program in ROM
* The mapper has been initialized (see [[Create_a_mapped_ROM#Initial_slot_configuration|Initial slot configuration]])
* The global variables have been initialized (so they have their predefined values)
* The <tt>main()</tt> function has not yet been called (so no program-specific initialization has taken place yet)

=== Notes ===
You must therefore ensure that the code you call within the callback function only calls functions that are visible to the Z80 in the given context:
* Within the first 16 KB for Konami, ASCII-16, and NEO-16 mappers, and plain-ROM.
* Within the first 8 KB for ASCII-8 and NEO-8 mappers.

As a reminder, the order of the module array (<tt>LibModules</tt>) in your program determines the location of each module in the final binary.

For example, if you want to call the MSX-Music detection function from the BIOS_OnRelease() callback, placing the <tt>msx-music</tt> module first in the list ensures that it appears at the beginning of the ROM.
<syntaxhighlight lang="c">
bool g_UseFM; // Used in BIOS_OnRelease (can't be initalized here)

//-----------------------------------------------------------------------------
// Event called before BIOS is released
void BIOS_OnRelease()
{
g_UseFM = (MSXMusic_Initialize() != MSXMUSIC_NOTFOUND);
}
</syntaxhighlight>

Build tool/BIOSReleaseEvent

2026-04-26T09:24:11Z

Aoineko:

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switched out from page 0. It allows you to have an initialization code that runs while the BIOS is still accessible at page 0. For example, to detect the presence of an MSX-Music device using the BIOS routines for cross-slot reading.

This applies to [[target]] formats that place the '''ROM on page 0''' (ROM_48K_ISR, ROM_64K_ISR, ROM_NEO8, and ROM_NEO16), as well as ROM formats that place '''RAM on page 0''' (via the [[Build_tool/InstallRAMISR|InstallRAMISR]] option).

== Usage ==
To use this option, you must provide a function that will be called by the boot process just before the BIOS is removed from page 0 (to make room for the cartridge or memory).

Function prototype:
<syntaxhighlight lang="c">void BIOS_OnRelease();</syntaxhighlight>

== Call context ==

You must be fully aware of the program's initialization context at the time the BIOS_OnRelease callback function is executed. This context depends on the type of target format.

=== ROM in page 0 ===
* The global variables have not been initialized yet (so you can't use those variables because their value is undefined and any change in the callback will be overwrite later during the boot process)
* The mapper has not yet been initialized;
** the selected segments are those selected by default by the hardware at the physical level (see https://www.msx.org/wiki/MegaROM_Mappers);
** mapper initialization will take place immediately after the return from the BIOS_OnRelease function and will overwrite any changes made in the callback;
* Only page 1 of memory space points to the program in ROM
* The <tt>main()</tt> function has not yet been called (so no program-specific initialization has taken place yet)

=== RAM in page 0 ===
* The global variables have been initialized (so they have their predefined values)
* The mapper has been initialized (see [[Create_a_mapped_ROM#Initial_slot_configuration|Initial slot configuration]])
* Pages 1 and 2 of memory point to the program in ROM
* The <tt>main()</tt> function has not yet been called (so no program-specific initialization has taken place yet)

=== Notes ===
You must therefore ensure that the code you call within the callback function only calls functions that are visible to the Z80 in the given context:
* Within the first 16 KB for Konami, ASCII-16, and NEO-16 mappers, and plain-ROM.
* Within the first 8 KB for ASCII-8 and NEO-8 mappers.

As a reminder, the order of the module array (<tt>LibModules</tt>) in your program determines the location of each module in the final binary.

For example, if you want to call the MSX-Music detection function from the BIOS_OnRelease() callback, placing the <tt>msx-music</tt> module first in the list ensures that it appears at the beginning of the ROM.
<syntaxhighlight lang="c">
bool g_UseFM; // Used in BIOS_OnRelease (can't be initalized here)

//-----------------------------------------------------------------------------
// Event called before BIOS is released
void BIOS_OnRelease()
{
g_UseFM = (MSXMusic_Initialize() != MSXMUSIC_NOTFOUND);
}
</syntaxhighlight>

Build tool/BIOSReleaseEvent

2026-04-26T09:23:24Z

Aoineko:

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switched out from page 0. It allows you to have an initialization code that runs while the BIOS is still accessible at page 0. For example, to detect the presence of an MSX-Music device using the BIOS routines for cross-slot reading.

This applies to [[target]] formats that place the ROM on page 0 (ROM_48K_ISR, ROM_64K_ISR, ROM_NEO8, and ROM_NEO16), as well as ROM formats that place RAM on page 0 (via the [[Build_tool/InstallRAMISR|InstallRAMISR]] option).

== Usage ==
To use this option, you must provide a function that will be called by the boot process just before the BIOS is removed from page 0 (to make room for the cartridge or memory).

Function prototype:
<syntaxhighlight lang="c">void BIOS_OnRelease();</syntaxhighlight>

== Call context ==

You must be fully aware of the program's initialization context at the time the BIOS_OnRelease callback function is executed. This context depends on the type of target format.

=== ROM in page 0 ===
* The global variables have not been initialized yet (so you can't use those variables because their value is undefined and any change in the callback will be overwrite later during the boot process)
* The mapper has not yet been initialized;
** the selected segments are those selected by default by the hardware at the physical level (see https://www.msx.org/wiki/MegaROM_Mappers);
** mapper initialization will take place immediately after the return from the BIOS_OnRelease function and will overwrite any changes made in the callback;
* Only page 1 of memory space points to the program in ROM
* The <tt>main()</tt> function has not yet been called (so no program-specific initialization has taken place yet)

=== RAM in page 0 ===
* The global variables have been initialized (so they have their predefined values)
* The mapper has been initialized (see [[Create_a_mapped_ROM#Initial_slot_configuration|Initial slot configuration]])
* Pages 1 and 2 of memory point to the program in ROM
* The <tt>main()</tt> function has not yet been called (so no program-specific initialization has taken place yet)

=== Notes ===
You must therefore ensure that the code you call within the callback function only calls functions that are visible to the Z80 in the given context:
* Within the first 16 KB for Konami, ASCII-16, and NEO-16 mappers, and plain-ROM.
* Within the first 8 KB for ASCII-8 and NEO-8 mappers.

As a reminder, the order of the module array (<tt>LibModules</tt>) in your program determines the location of each module in the final binary.

For example, if you want to call the MSX-Music detection function from the BIOS_OnRelease() callback, placing the <tt>msx-music</tt> module first in the list ensures that it appears at the beginning of the ROM.
<syntaxhighlight lang="c">
bool g_UseFM; // Used in BIOS_OnRelease (can't be initalized here)

//-----------------------------------------------------------------------------
// Event called before BIOS is released
void BIOS_OnRelease()
{
g_UseFM = (MSXMusic_Initialize() != MSXMUSIC_NOTFOUND);
}
</syntaxhighlight>

Pixel Phenix

2026-04-23T21:17:06Z

Aoineko:

<img src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/refs/heads/main/engine/doc/img/phenix.png" style="width:192px; image-rendering:pixelated; float:right;" />
'''Pixel Phenix''' is an MSX video game creation group whose objectives are:
* Create a high-quality gaming experience:
** Precise, fluid and responsive gameplay,
** High-quality graphics that take advantage of the machine's capabilities,
** Immersive storytelling (when applicable).
* Ensure a polished finalization:
** In-depth playtesting of the game,
** Debugging to remove known issues and instabilities.
* Make the best use of the hardware capabilities and available features (MSX1 game with MSX2 enhancement for example).
* Maintain maximum compatibility (if MSX1 is enough for the game concept, go for it).

== Members ==
* Guillaume "Aoineko"
* Ludo "GFX"

== Games ==
* '''''Crawlers''''' [PH-001] (2023)
* '''''Room 5''''' (2025, in association with [https://mo5.com MO5.com])
* '''''Peng Pong''''' [PH-003] (2025)
* '''''Soul Trapped''''' (2026, in association with [https://caspercroes.itch.io Casper Croes])
* '''''Wizzl''''' [PH-004] (WIP)
* '''''Final Smash''''' [PH-002] (WIP)

Pixel Phenix

2026-04-23T21:16:31Z

Aoineko:

<img src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/refs/heads/main/engine/doc/img/phenix.png" style="width:192px; image-rendering:pixelated; float:right;" />
'''Pixel Phenix''' is an MSX video game creation group whose objectives are:
* Create a high-quality gaming experience:
** Precise, fluid and responsive gameplay,
** High-quality graphics that take advantage of the machine's capabilities,
** Immersive storytelling (where applicable).
* Ensure a polished finalization:
** In-depth playtesting of the game,
** Debugging to remove known issues and instabilities.
* Make the best use of the hardware capabilities and available features (MSX1 game with MSX2 enhancement for example).
* Maintain maximum compatibility (if MSX1 is enough for the game concept, go for it).

== Members ==
* Guillaume "Aoineko"
* Ludo "GFX"

== Games ==
* '''''Crawlers''''' [PH-001] (2023)
* '''''Room 5''''' (2025, in association with [https://mo5.com MO5.com])
* '''''Peng Pong''''' [PH-003] (2025)
* '''''Soul Trapped''''' (2026, in association with [https://caspercroes.itch.io Casper Croes])
* '''''Wizzl''''' [PH-004] (WIP)
* '''''Final Smash''''' [PH-002] (WIP)

Pixel Phenix

2026-04-23T21:15:16Z

Aoineko:

<img src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/refs/heads/main/engine/doc/img/phenix.png" style="width:192px; image-rendering:pixelated; float:right;" />
'''Pixel Phenix''' is an MSX video game creation group whose objectives are:
* Create a high-quality gaming experience:
** Precise, fluid and responsive gameplay,
** High-quality graphics that take advantage of the machine's capabilities,
** Immersive storytelling (where applicable).
* Ensure a polished finalization:
** In-depth playtesting of the game,
** Debugging to remove known issues and instabilities.
* Make the best use of the hardware capabilities and available features (MSX1 game with MSX2 enhancement for example).
* Maintain maximum compatibility (if MSX1 is enough for the game concept, go for it).

== Members ==
* Guillaume "Aoineko"
* Ludo "GFX"

== Games ==
* '''''Crawlers''''' [PH-001] (2023)
* '''''Room 5''''' (2025, in association with [https://mo5.com MO5.com])
* '''''Peng Pong''''' [PH-003] (2025)
* '''''Soul Trapped''''' (2026, in association with Casper Croes)
* '''''Wizzl''''' [PH-004] (WIP)
* '''''Final Smash''''' [PH-002] (WIP)

Build tool/BIOSReleaseEvent

2026-04-23T20:15:58Z

Aoineko:

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switched out from page 0. It allows you to have an initialization code that runs while the BIOS is still accessible at page 0. For example, to detect the presence of an MSX-Music device using the BIOS routines for cross-slot reading.

This applies to [[target]] formats that place the ROM on page 0 (ROM_48K_ISR, ROM_64K_ISR, ROM_NEO8, and ROM_NEO16), as well as ROM formats that place RAM on page 0 (via the [[Build_tool/InstallRAMISR|InstallRAMISR]] option).

== Usage ==
To use this option, you must provide a function that will be called by the boot process just before the BIOS is removed from page 0 (to make room for the cartridge or memory).

Function prototype:
<syntaxhighlight lang="c">void BIOS_OnRelease();</syntaxhighlight>

== Call context ==

You must be fully aware of the program's initialization context at the time the BIOS_OnRelease callback function is executed. This context depends on the type of target format.

=== ROM in page 0 ===
* The global variables have not been initialized yet (so you can't use those variables because their value is undefined and any change in the callback will be overwrite later during the boot process)
* The <tt>main()</tt> function has not yet been called (so no program-specific initialization has taken place yet)
* The mapper has not yet been initialized;
** the selected segments are those selected by default by the hardware at the physical level (see https://www.msx.org/wiki/MegaROM_Mappers);
** mapper initialization will take place immediately after the return from the BIOS_OnRelease function and will overwrite any changes made in the callback;
* Only page 1 of memory space points to the program in ROM

=== RAM in page 0 ===
* The global variables have been initialized (so they have their predefined values)
* The <tt>main()</tt> function has not yet been called (so no program-specific initialization has taken place yet)
* The mapper has been initialized (see [[Create_a_mapped_ROM#Initial_slot_configuration|Initial slot configuration]])
* Pages 1 and 2 of memory point to the program in ROM

=== Notes ===
You must therefore ensure that the code you call within the callback function only calls functions that are visible to the Z80 in the given context:
* Within the first 16 KB for Konami, ASCII-16, and NEO-16 mappers, and plain-ROM.
* Within the first 8 KB for ASCII-8 and NEO-8 mappers.

As a reminder, the order of the module array (<tt>LibModules</tt>) in your program determines the location of each module in the final binary.

For example, if you want to call the MSX-Music detection function from the BIOS_OnRelease() callback, placing the <tt>msx-music</tt> module first in the list ensures that it appears at the beginning of the ROM.
<syntaxhighlight lang="c">
bool g_UseFM; // Used in BIOS_OnRelease (can't be initalized here)

//-----------------------------------------------------------------------------
// Event called before BIOS is released
void BIOS_OnRelease()
{
g_UseFM = (MSXMusic_Initialize() != MSXMUSIC_NOTFOUND);
}
</syntaxhighlight>

Build tool/BIOSReleaseEvent

2026-04-23T20:13:14Z

Aoineko: /* Call context */

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switched out from page 0. It allows you to have an initialization code that runs while the BIOS is still accessible at page 0. For example, to detect the presence of an MSX-Music device using the BIOS routines for cross-slot reading.

This applies to [[target]] formats that place the ROM on page 0 (ROM_48K_ISR, ROM_64K_ISR, ROM_NEO8, and ROM_NEO16), as well as ROM formats that place RAM on page 0 (via the [[Build_tool/InstallRAMISR|InstallRAMISR]] option).

== Usage ==
To use this option, you must provide a function that will be called by the boot process just before the BIOS is removed from page 0 (to make room for the cartridge or memory).

Function prototype:
<syntaxhighlight lang="c">void BIOS_OnRelease();</syntaxhighlight>

== Call context ==

You must be fully aware of the program's initialization context at the time the BIOS_OnRelease callback function is executed. This context depends on the type of target format.

=== ROM in page 0 ===
* The global variables have not been initialized yet (so you can't use those variables because their value is undefined and any change in the callback will be overwrite later during the boot process)
* The <tt>main()</tt> function has not yet been called (so no program-specific initialization has taken place yet)
* The mapper has not yet been initialized;
** the selected segments are those selected by default by the hardware at the physical level (see https://www.msx.org/wiki/MegaROM_Mappers);
** mapper initialization will take place immediately after the return from the BIOS_OnRelease function and will overwrite any changes made in the callback;
* Only page 1 of memory space points to the program in ROM

=== RAM in page 0 ===
* The global variables have been initialized (so they have their predefined values)
* The <tt>main()</tt> function has not yet been called (so no program-specific initialization has taken place yet)
* The mapper has been initialized (see [[Create_a_mapped_ROM#Initial_slot_configuration|Initial slot configuration]])
* Pages 1 and 2 of memory point to the program in ROM

=== Notes ===
You must therefore ensure that the code you call within the callback function only calls functions that are visible to the Z80 in the given context:
* Within the first 16 KB for Konami, ASCII-16, and NEO-16 mappers, and plain-ROM.
* Within the first 8 KB for ASCII-8 and NEO-8 mappers.

As a reminder, the order of the module array (<tt>LibModules</tt>) in your program determines the location of each module in the final binary.

For example, if you want to call the MSX-Music detection function from the BIOS_OnRelease() callback, placing the <tt>msx-music</tt> module first in the list ensures that it appears at the beginning of the ROM.

Build tool/BIOSReleaseEvent

2026-04-23T20:12:53Z

Aoineko: /* ROM in page 0 */

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switched out from page 0. It allows you to have an initialization code that runs while the BIOS is still accessible at page 0. For example, to detect the presence of an MSX-Music device using the BIOS routines for cross-slot reading.

This applies to [[target]] formats that place the ROM on page 0 (ROM_48K_ISR, ROM_64K_ISR, ROM_NEO8, and ROM_NEO16), as well as ROM formats that place RAM on page 0 (via the [[Build_tool/InstallRAMISR|InstallRAMISR]] option).

== Usage ==
To use this option, you must provide a function that will be called by the boot process just before the BIOS is removed from page 0 (to make room for the cartridge or memory).

Function prototype:
<syntaxhighlight lang="c">void BIOS_OnRelease();</syntaxhighlight>

== Call context ==

You must be fully aware of the program's initialization context at the time the BIOS_OnRelease callback function is executed. This context depends on the type of target format.

=== ROM in page 0 ===
* The global variables have not been initialized yet (so you can't use those variables because their value is undefined and any change in the callback will be overwrite later during the boot process)
* The main() function has not yet been called (so no program-specific initialization has taken place yet)
* The mapper has not yet been initialized;
** the selected segments are those selected by default by the hardware at the physical level (see https://www.msx.org/wiki/MegaROM_Mappers);
** mapper initialization will take place immediately after the return from the BIOS_OnRelease function and will overwrite any changes made in the callback;
* Only page 1 of memory space points to the program in ROM

=== RAM in page 0 ===
* The global variables have been initialized (so they have their predefined values)
* The main() function has not yet been called (so no program-specific initialization has taken place yet)
* The mapper has been initialized (see [[Create_a_mapped_ROM#Initial_slot_configuration|Initial slot configuration]])
* Pages 1 and 2 of memory point to the program in ROM

=== Notes ===
You must therefore ensure that the code you call within the callback function only calls functions that are visible to the Z80 in the given context:
* Within the first 16 KB for Konami, ASCII-16, and NEO-16 mappers, and plain-ROM.
* Within the first 8 KB for ASCII-8 and NEO-8 mappers.

As a reminder, the order of the module array (<tt>LibModules</tt>) in your program determines the location of each module in the final binary.

For example, if you want to call the MSX-Music detection function from the BIOS_OnRelease() callback, placing the <tt>msx-music</tt> module first in the list ensures that it appears at the beginning of the ROM.

Build tool/BIOSReleaseEvent

2026-04-23T20:10:19Z

Aoineko: /* Usage */

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switched out from page 0. It allows you to have an initialization code that runs while the BIOS is still accessible at page 0. For example, to detect the presence of an MSX-Music device using the BIOS routines for cross-slot reading.

This applies to [[target]] formats that place the ROM on page 0 (ROM_48K_ISR, ROM_64K_ISR, ROM_NEO8, and ROM_NEO16), as well as ROM formats that place RAM on page 0 (via the [[Build_tool/InstallRAMISR|InstallRAMISR]] option).

== Usage ==
To use this option, you must provide a function that will be called by the boot process just before the BIOS is removed from page 0 (to make room for the cartridge or memory).

Function prototype:
<syntaxhighlight lang="c">void BIOS_OnRelease();</syntaxhighlight>

== Call context ==

You must be fully aware of the program's initialization context at the time the BIOS_OnRelease callback function is executed. This context depends on the type of target format.

=== ROM in page 0 ===
* The global variables have been initialized (so they have their predefined values)
* The main() function has not yet been called (so no program-specific initialization has taken place yet)
* The mapper has not yet been initialized;
** the selected segments are those selected by default by the hardware at the physical level (see https://www.msx.org/wiki/MegaROM_Mappers);
** mapper initialization will take place immediately after the return from the BIOS_OnRelease function and will overwrite any changes made in the callback;
* Only page 1 of memory space points to the program in ROM

=== RAM in page 0 ===
* The global variables have been initialized (so they have their predefined values)
* The main() function has not yet been called (so no program-specific initialization has taken place yet)
* The mapper has been initialized (see [[Create_a_mapped_ROM#Initial_slot_configuration|Initial slot configuration]])
* Pages 1 and 2 of memory point to the program in ROM

=== Notes ===
You must therefore ensure that the code you call within the callback function only calls functions that are visible to the Z80 in the given context:
* Within the first 16 KB for Konami, ASCII-16, and NEO-16 mappers, and plain-ROM.
* Within the first 8 KB for ASCII-8 and NEO-8 mappers.

As a reminder, the order of the module array (<tt>LibModules</tt>) in your program determines the location of each module in the final binary.

For example, if you want to call the MSX-Music detection function from the BIOS_OnRelease() callback, placing the <tt>msx-music</tt> module first in the list ensures that it appears at the beginning of the ROM.

Build tool/BIOSReleaseEvent

2026-04-19T11:07:13Z

Aoineko:

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switched out from page 0. It allows you to have an initialization code that runs while the BIOS is still accessible at page 0. For example, to detect the presence of an MSX-Music device using the BIOS routines for cross-slot reading.

This applies to [[target]] formats that place the ROM on page 0 (ROM_48K_ISR, ROM_64K_ISR, ROM_NEO8, and ROM_NEO16), as well as ROM formats that place RAM on page 0 (via the [[Build_tool/InstallRAMISR|InstallRAMISR]] option).

== Usage ==
To use this option, the user must provide a function that will be called by the boot process just before the BIOS is removed from page 0 (to make room for the cartridge or memory).

Function prototype:
<syntaxhighlight lang="c">void BIOS_OnRelease();</syntaxhighlight>

== Call context ==

You must be fully aware of the program's initialization context at the time the BIOS_OnRelease callback function is executed. This context depends on the type of target format.

=== ROM in page 0 ===
* The global variables have been initialized (so they have their predefined values)
* The main() function has not yet been called (so no program-specific initialization has taken place yet)
* The mapper has not yet been initialized;
** the selected segments are those selected by default by the hardware at the physical level (see https://www.msx.org/wiki/MegaROM_Mappers);
** mapper initialization will take place immediately after the return from the BIOS_OnRelease function and will overwrite any changes made in the callback;
* Only page 1 of memory space points to the program in ROM

=== RAM in page 0 ===
* The global variables have been initialized (so they have their predefined values)
* The main() function has not yet been called (so no program-specific initialization has taken place yet)
* The mapper has been initialized (see [[Create_a_mapped_ROM#Initial_slot_configuration|Initial slot configuration]])
* Pages 1 and 2 of memory point to the program in ROM

=== Notes ===
You must therefore ensure that the code you call within the callback function only calls functions that are visible to the Z80 in the given context:
* Within the first 16 KB for Konami, ASCII-16, and NEO-16 mappers, and plain-ROM.
* Within the first 8 KB for ASCII-8 and NEO-8 mappers.

As a reminder, the order of the module array (<tt>LibModules</tt>) in your program determines the location of each module in the final binary.

For example, if you want to call the MSX-Music detection function from the BIOS_OnRelease() callback, placing the <tt>msx-music</tt> module first in the list ensures that it appears at the beginning of the ROM.

Build tool/BIOSReleaseEvent

2026-04-19T11:06:59Z

Aoineko:

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switched out from page 0. It allows you to have an initialization code that runs while the BIOS is still accessible at page 0. For example, to detect the presence of an MSX-Music device using the BIOS routines for cross-slot reading.

This applies to [[target]] formats that place the ROM on page 0 (ROM_48K_ISR, ROM_64K_ISR, ROM_NEO8, and ROM_NEO16), as well as ROM formats that place RAM on page 0 (via the [[Build_tool/InstallRAMISR|InstallRAMISR]] option).

== Usage ==
To use this option, the user must provide a function that will be called by the boot process just before the BIOS is removed from page 0 (to make room for the cartridge or memory).

Function prototype:
<syntaxhighlight lang="c">void BIOS_OnRelease();</syntaxhighlight>

== Call context ==

You must be fully aware of the program's initialization context at the time the BIOS_OnRelease callback function is executed. This context depends on the type of target format.

=== ROM in page 0 ===
* The global variables have been initialized (so they have their predefined values)
* The main() function has not yet been called (so no program-specific initialization has taken place yet)
* The mapper has not yet been initialized;
** the selected segments are those selected by default by the hardware at the physical level (see https://www.msx.org/wiki/MegaROM_Mappers);
** mapper initialization will take place immediately after the return from the BIOS_OnRelease function and will overwrite any changes made in the callback;
* Only page 1 of memory space points to the program in ROM

=== RAM in page 0 ===
* The global variables have been initialized (so they have their predefined values)
* The main() function has not yet been called (so no program-specific initialization has taken place yet)
* The mapper has been initialized (see [[Create_a_mapped_ROM#Initial_slot_configuration|Initial slot configuration]])
* Pages 1 and 2 of memory point to the program in ROM

=== Notes ===
You must therefore ensure that the code you call within the callback function only calls functions that are visible to the Z80 in the given context:
* Within the first 16 KB for Konami, ASCII-16, and NEO-16 mappers, and plain-ROM.
* Within the first 8 KB for ASCII-8 and NEO-8 mappers.

As a reminder, the order of the module array (<tt>LibModules</tt>) in your program determines the location of each module in the final binary.

For example, if you want to call the MSX-Music detection function from the BIOS_OnRelease() callback, placing the <tt>msx-music</tt> module first in the list ensures that it appears at the beginning of the ROM.

Build tool/BIOSReleaseEvent

2026-04-19T10:58:36Z

Aoineko:

Build tool/BIOSReleaseEvent

2026-04-19T10:58:04Z

Aoineko:

Build tool/BIOSReleaseEvent

2026-04-19T10:17:44Z

Aoineko:

Build tool/BIOSReleaseEvent

2026-04-19T10:17:28Z

Aoineko:

Build tool/BIOSReleaseEvent

2026-04-19T10:11:27Z

Aoineko:

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switched out from page 0.

This applies to [[target]] formats that place the ROM on page 0 (ROM_48K_ISR, ROM_64K_ISR, ROM_NEO8, and ROM_NEO16), as well as ROM formats that place RAM on page 0 (via the [[Build_tool/InstallRAMISR|InstallRAMISR]] option).

Build tool/BIOSReleaseEvent

2026-04-19T10:11:18Z

Aoineko:

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switched out from page 0. This applies to [[target]] formats that place the ROM on page 0 (ROM_48K_ISR, ROM_64K_ISR, ROM_NEO8, and ROM_NEO16), as well as ROM formats that place RAM on page 0 (via the [[Build_tool/InstallRAMISR|InstallRAMISR]] option).

Build tool

2026-04-19T08:18:02Z

Aoineko: /* Project */

The '''Build tool''' is the {{MSXGL}} script that will create your final program for MSX.

It is fully configurable by the user. For example, it is here that we can choose whether we want our game to be available in ROM, MSX-DOS or BASIC binary format. Or if our program should be MSX1 compatible or only MSX2+ for example.

The Build tool is written in JavaScript and executed via Node.js. All the programs needed to run the script are available in MSXgl and the user does not need to install anything.

Build tool is started from the project directory via a script that depends on the platform:
* On Windows, run <tt>build.bat</tt>,
* On Linux, run <tt>./build.sh</tt>.

See the <tt>example</tt> or <tt>template</tt> project for an actual use case.

== Configuration ==

The Build tool configuration's parameters are defined in the '''engine''' (<tt>engine/script/js/setup_global.js</tt>) and can be overwrite by the user at two levels:
* The '''default''' configuration (<tt>projects/default_config.js</tt>), commun for all the projects.
* The '''project''' configuration (<tt>projects/myProject/project_config.js</tt>), specific for a given project.

The value of the parameters redefined in a higher level replaces that of a lower level.

Some parameters can be overwrite as command-line parameters (see [[#Command-line overwrite|Command-line overwrite]] section).

The order of '''priority''' is: Command-line > Project config > Default config > Engine config.

== Build parameters ==

=== Stage ===
The build tool is divided into several stages that you can choose to activate or deactivate at will.

{{PARAM|DoClean|Clear all intermediate files and exit|boolean|false}}

{{PARAM|DoCompile|Compile all the project and engine source code. Generate all REL files|boolean|true}}

{{PARAM|DoMake|Link all the project and engine source code. Merge all REL into one IHX file|boolean|true}}

{{PARAM|DoPackage|Generate final binary file (boolean). Binarize the IHX file|boolean|true}}

{{PARAM|DoDeploy|Gathering of all files necessary for the program to work (boolean). Depends on the type of target|boolean|true}}

{{PARAM|DoRun|Start the program automatically at the end of the build|boolean|false}}

=== Path ===

{{PARAM|ProjDir|Project directory|string|}}

{{PARAM|OutDir|Intermediate files directory|string|`${ProjDir}out/`}}

{{PARAM|RootDir|MSXgl root directory|string|}}

{{PARAM|LibDir|Library directory|string|`${RootDir}engine/`}}

{{PARAM|ToolsDir|Tools directory|string|`${RootDir}tools/`}}

=== Tools ===

{{PARAM|SDCCPath|Path to SDCC tools chain|string|`${ToolsDir}sdcc/`}}

{{PARAM|Compiler|Path to the C compile program|string|`${SDCCPath}bin/sdcc`}}

{{PARAM|Assembler|Path to the assembler program|string|`${SDCCPath}bin/sdasz80`}}

{{PARAM|Linker|Path to the linker program|string|`${SDCCPath}bin/sdcc`}}

{{PARAM|MakeLib|Path to the program to generate lib file|string|`${SDCCPath}bin/sdar`}}

{{PARAM|Hex2Bin|Path to IHX to binary convertor|string|`${ToolsDir}MSXtk/bin/MSXhex`}}

{{PARAM|MSXDOS|Path to the MSX-DOS files|string|`${ToolsDir}build/DOS/`}}

{{PARAM|DskTool|Path to the tool to generate DSK file|string|`${ToolsDir}build/msxtar/msxtar`}}

{{PARAM|Emulator|Path to the emulator to launch the project|string|}}

=== Project ===

{{PARAM|ProjName|Project name. Will be use for output filename|string|}}

{{PARAM|ProjModules|List of project modules to build. If empty, ProjName will be added|array|}}

{{PARAM|ProjSegments|Project segments base name. ProjName will be used if not defined|string|}}

{{PARAM|LibModules|List of library modules to build|array|}}

{{PARAM|AddSources|Additional sources to be compiled and linked with the project|array|}}

{{PARAM|AddLibs|Additional extern library to be linked with the project|array|}}

{{PARAM|Machine|Target MSX machine version|string|"1"}}
<syntaxhighlight lang="js">
// - 1 MSX1
// - 2 MSX2
// - 12 MSX1 and 2 (multi support)
// - 2K Korean MSX2 (SC9 support)
// - 2P MSX2+
// - 22P MSX2 and 2+ (multi support)
// - 122P MSX1, 2 and 2+ (multi support)
// - 0 MSX0
// - TR MSX turbo R
// - 3 MSX3 (reserved)
</syntaxhighlight>
Multi support means that the application can use the features of all supported MSX generations. The user must detect the MSX version at runtime and adjust the program accordingly.

{{PARAM|Target|Target program format|string|"ROM_32K"}}
<syntaxhighlight lang="js">
// - BIN_DISK .bin BASIC binary program (starting at 8000h) on disk
// - BIN_TAPE .bin BASIC binary program (starting at 8000h) on tape
// - BIN_USR .bin BASIC USR binary driver (starting at C000h)
// - DOS1 .com MSX-DOS 1 program (starting at 0100h)
// - DOS2 .com MSX-DOS 2 program (starting at 0100h)
// - DOS0 .com Direct program boot from disk (starting at 0100h)
// - ROM_8K .rom 8 KB ROM in page 1 (4000h ~ 5FFFh)
// - ROM_8K_P2 .rom 8 KB ROM in page 2 (8000h ~ 9FFFh)
// - ROM_16K .rom 16 KB ROM in page 1 (4000h ~ 7FFFh)
// - ROM_16K_P2 .rom 16 KB ROM in page 2 (8000h ~ BFFFh)
// - ROM_32K .rom 32 KB ROM in page 1&2 (4000h ~ BFFFh)
// - ROM_48K .rom 48 KB ROM in page 0-2 (0000h ~ BFFFh)
// - ROM_48K_ISR .rom 48 KB ROM in page 0-2 (0000h ~ BFFFh) with ISR replacement
// - ROM_64K .rom 64 KB ROM in page 0-3 (0000h ~ FFFFh)
// - ROM_64K_ISR .rom 64 KB ROM in page 0-3 (0000h ~ FFFFh) with ISR replacement
// - ROM_ASCII8 .rom ASCII-8: 8 KB segments for a total of 64 KB to 2 MB
// - ROM_ASCII16 .rom ASCII-16: 16 KB segments for a total of 64 KB to 4 MB
// - ROM_KONAMI .rom Konami MegaROM (aka Konami4): 8 KB segments for a total of 64 KB to 2 MB
// - ROM_KONAMI_SCC .rom Konami MegaROM SCC (aka Konami5): 8 KB segments for a total of 64 KB to 2 MB
// - ROM_NEO8 .rom NEO-8: 8 KB segments for a total of 1 MB to 32 MB
// - ROM_NEO16 .rom NEO-16: 16 KB segments for a total of 1 MB to 64 MB
// - ROM_YAMANOOTO .rom Yamanooto: 8 KB segments for a total up to 8 MB
// - ROM_ASCII16X .rom ASCII16-X: 16 KB segments for a total up to 64 MB
// - RAW .bin Raw binary code and data to be compiled at a given address
// - LIB .lib C library to be included in other project
</syntaxhighlight>
More detail: [[Targets]]

{{PARAM|ROMSize|ROM mapper total size in KB. Must be a multiple of 8 or 16 depending on the mapper type (from 64 to 4096)|number|128}}

{{PARAM|ROMMainSegments|Number of segments in the main program of a mapped-ROM. 0 means 'number of segments to fill 32 KB of ROM|number|0}}

{{PARAM|ROMSkipBoot|Check for ROM boot skipping if a given key is pressed|boolean|false}}

{{PARAM|ROMSkipBootKey|The key to be check for ROM boot skipping. Key must be from keyboard row #7|string|"ESC"}}
<syntaxhighlight lang="js">
// - F4
// - F5
// - ESC
// - TAB
// - STOP
// - BS
// - SELECT
// - RETURN
</syntaxhighlight>

{{PARAM|ROMDelayBoot|Postpone the ROM startup to let the other ROMs initialize like Disk controller or Network cartridge|boolean|false}}

{{PARAM|AddROMSignature|Add a ROM signature to help flasher and emulator to detect the ROM type properly|boolean|false}}

{{PARAM|InstallRAMISR|Select RAM in slot 0 and install ISR and optional code there. For MSX with at least 64 KB of RAM|string|"RAM0_NONE"}}
<syntaxhighlight lang="js">
// - RAM0_NONE Don't install anything in RAM
// - RAM0_ISR Install only ISR
// - RAM0_SEGMENT Install ISR and segment data (for mapped-ROM)
</syntaxhighlight>
For mode detail about usage of RAM0_SEGMENT, check [[Build tool/InstallRAMISR|this document]].

{{PARAM|CustomISR|Type of custom ISR to install. ISR is install in RAM or ROM depending on Target and InstallRAMISR parameters|string|"VBLANK"}}
<syntaxhighlight lang="js">
// - NONE No ISR
// - ALL Handle all interruptions
// - VBLANK V-blank handler
// - VHBLANK V-blank and h-blank handler (V9938 or V9958)
// - V9990 V-blank, h-blank and command end handler (V9990)
</syntaxhighlight>
Depending on the selected ISR, some functions must be provided by the user:
<syntaxhighlight lang="c">
// CustomISR = "ALL"
VDP_InterruptHandler(); // All interrupt

// CustomISR = "VBLANK"
VDP_InterruptHandler(); // V-blank interrupt

// CustomISR = "VHBLANK"
VDP_InterruptHandler(); // V-blank interrupt
VDP_HBlankHandler(); // H-blank interrupt

// CustomISR = "V9990"
V9_InterruptVBlank(); // V-blank interrupt
V9_InterruptHBlank(); // H-blank interrupt
V9_InterruptCommand(); // Command end interrupt
</syntaxhighlight>

{{PARAM|BIOSReleaseEvent|Event called before BIOS is released. For target format that switch out BIOS from page 0.|boolean|false}}
More detail: [[Build tool/BIOSReleaseEvent|BIOSReleaseEvent]]

{{PARAM|CheckVersion|Add code to check MSX version at program startup. Works for ROM and BASIC program.|boolean|false}}

{{PARAM|BankedCall|Use automatic banked call and trampoline functions (for mapped ROM)|boolean|false}}

{{PARAM|ForceCodeAddr|Overwrite code starting address. For example. 0xE0000 for a driver in RAM|number|0}}

{{PARAM|ForceRamAddr|Overwrite RAM starting address. For example. 0xE0000 for 8K RAM machine|number|0}}

{{PARAM|RawFiles|List of raw data files to be added to the final binary|array|}}
Raw files can be added to final binary by defining 3 types of position: <tt>offset</tt>, <tt>segment</tt> or <tt>page</tt>.
<syntaxhighlight lang="js">
// Sample example
RawFiles = [
{ offset: 0x10000, file: "file1.bin" }, // Offset from final binary start
{ segment: 7, file: "file2.bin" }, // Segment number for mapped-ROM
{ page: 0, file: "file.bin" }, // Page number (16 KB) in the final binary
];
</syntaxhighlight>
Notes:
* If the <tt>RawFiles</tt> table is not empty, the Build tool will generate a definition header file (<tt>myproject_rawdef.h</tt>) with information to access the raw binary data from code.
* More than one file can be add to the same page or mapper segment. In this case, data will be concatenated in the table order, and definition header file (see above) is needed to know the offset (relative to page / segment) where data is located.
* When using page 0 (0x0000~0x3FFF), data will be placed from address 0x0100 (after the area reserved for the ISR).

{{PARAM|DiskFiles|List of data files to copy to disk|array|}}

{{PARAM|DiskSize|Size of the final disk (.DSK file). Can be "360K" or "720K"|string|"720K"}}

{{PARAM|DOSParseArg|Parse MSX-DOS command-line arguments|boolean|true}}

=== Signature ===
{{PARAM|AppSignature|Add application signature to binary data|boolean|false}}

{{PARAM|AppCompany|Application company. Can be 2 character string or 16-bits integer|string/number|"GL"}}

{{PARAM|AppID|Application ID. Can be 2 character string or 16-bits integer (0~65535)|string/number|0}}

{{PARAM|AppExtra|Application extra data. Comma-separated bytes starting with data size|array|}}

Note: See [[AppSignature]] and [[AppExtra]] for more details.

=== Make ===

{{PARAM|BuildLibrary|Force to generate MSXgl static library even if 'msxgl.lib' already exist|bolean|true}}

{{PARAM|Debug|Prepare program for debug|boolean|false}}

{{PARAM|DebugSymbols|Move debug symbols to deployement folder|boolean|false}}

{{PARAM|AllowUndocumented|Allow compiler to generate undocumented Z80 instructions|boolean|true}}

{{PARAM|AsmOptim|Assembler code optimizer ⚠️ WIP|string|"None"}}
<syntaxhighlight lang="js">
// - None
// - Peep SDCC peep hole otpimizer
// - MDL MDL z80 otpimizer
</syntaxhighlight>

{{PARAM|Optim|Code optimization priority|string|"Speed"}}
<syntaxhighlight lang="js">
// - Default
// - Speed
// - Size
</syntaxhighlight>

{{PARAM|CompileComplexity|Compile complexity. The higher the most optimized but the slowest to compile. Can be one of the predefine name or a integer value.|string/integer|"Default"}}
<syntaxhighlight lang="js">
// - Fast 2000
// - Default 3000
// - Optimized 50000
// - Ultra 200000
// - Insane 10000000
</syntaxhighlight>

{{PARAM|CompileOpt|Additionnal compilation flag|string|}}

{{PARAM|CompileSkipOld|Skip file if compiled data (REL) is newer than the source code|boolean|false}}

{{PARAM|LinkOpt|Additionnal link options|string|}}

{{PARAM|BuildVersion|Automatic increment of build version in a header file|boolean|false}}

{{PARAM|PackSegments|Package all segments into a lib file to reduce the number of files to link|boolean|false}}

{{PARAM|GenCompileDB|Generate Clang compatible Compilation database|boolean|false}}

{{PARAM|HexBinOpt|Additionnal options of Hex to Binary convertor|string|""}}

{{PARAM|PreBuildScripts|Command lines to be executed before the build process|array|[]}}

{{PARAM|PostBuildScripts|Command lines to be executed after the build process|array|[]}}

=== Localization ===

{{PARAM|LocFiles|List files to be localized|array|}}

{{PARAM|LocOutput|Localization output filename|string|"localization.h"}}

{{PARAM|LocStruct|Localization structure name|string|"g_LocData"}}

{{PARAM|LocSplitDef|Split socalization data and definitions in different files|boolean|false}}

For example:
<syntaxhighlight lang="js">
//-- List files to be localized (array)
LocFiles = [ "translate_en.ini", "translate_fr.ini", "translate_ja.ini" ];

//-- Localization output filename (string)
LocOutput = "data/translate.h";

//-- Localization structure name (string)
LocStruct = "g_TransData";

//-- Split socalization data and definitions in different files (boolean)
LocSplitDef = true;
</syntaxhighlight>

=== Build Tool ===

{{PARAM|Verbose|Activate verbose mode and get more build information|boolean|false}}

{{PARAM|LogStdout|Output build information to the standard console|boolean|true}}

{{PARAM|LogFile|Output build information to a log file|boolean|false}}

{{PARAM|LogFileName|Name of the log file|string|"log_YYYYMMDD_HHMMSS.txt"}}

=== Analyzer ===

{{PARAM|Analyzer|Execute compiler analyzer|boolean|true}}

{{PARAM|AnalyzerOutput|Analyzer output selection|string|Both}}
<syntaxhighlight lang="js">
// - Console Output to termial console
// - File Output to file
// - Both Output to file and termial console (default)
</syntaxhighlight>

{{PARAM|AnalyzerReport|Analyzer report elements|string|ASMCV}}
<syntaxhighlight lang="js">
// - [A] Report areas
// - [S] Report segments
// - [M] Report modules
// - [C] Report code symbols
// - [V] Report variable symbols
</syntaxhighlight>

{{PARAM|AnalyzerSort|Analyzer report sorting|string|Size}}
<syntaxhighlight lang="js">
// - None No sorting (MAP file order)
// - Alpha Alphanumeric sorting
// - Size Size sorting (default)
</syntaxhighlight>

{{PARAM|AnalyzerCSV|Export analyzer data to CSV file|boolean|false}}

{{PARAM|AnalyzerSeparator|Analyzer CSV file separator|string|","}}

=== Package ===

{{PARAM|Standalone|Should the build tool create a standalone package?|boolean|false}}

Note: Package is created in a <tt>/package/</tt> folder at the root of the project.

=== Emulator ===

==== General ====
{{PARAM|EmulMachine|Force the MSX version of the emulated machine|boolean|true}}

{{PARAM|Emul60Hz|Force the emulated machine to be at 60 Hz|boolean|false}}

{{PARAM|EmulFullScreen|Force the emulator to start in fullscreen mode|boolean|false}}

{{PARAM|EmulMute|Disable emulator sound|boolean|false}}

{{PARAM|EmulDebug|Start emulator debugger with program launch|boolean|false}}

{{PARAM|EmulTurbo|Start emulator in turbo mode|boolean|false}}

{{PARAM|EmulExtraParam|Emulator extra parameters to be add to command-line. Emulator sotfware specific|string|}}

==== Extensions ====
{{PARAM|EmulSCC|Add SCC extension|boolean|false}}

{{PARAM|EmulMSXMusic|Add MSX-Music extension|boolean|false}}

{{PARAM|EmulMSXAudio|Add MSX-Audio extension|boolean|false}}

{{PARAM|EmulOPL4|Add OPL4 extension|boolean|false}}

{{PARAM|EmulPSG2|Add second PSG extension|boolean|false}}

{{PARAM|EmulV9990|Add V9990 video-chip extension|boolean|false}}

{{PARAM|EmulRAM|Add mapped-RAM extension|boolean|false}}

Note: The biggest available RAM extension will be selected (4 MB if supported)

==== Input ====
{{PARAM|EmulPortA|Plug a virtual device into the joystick port A|string|}}
<syntaxhighlight lang="js">
// - Joystick
// - Mouse
// - Paddle
// - JoyMega
// - NinjaTap
</syntaxhighlight>

{{PARAM|EmulPortB|Plug a virtual device into the joystick port B|string|}}
<syntaxhighlight lang="js">
// - Joystick
// - Mouse
// - Paddle
// - JoyMega
// - NinjaTap
</syntaxhighlight>

==== Run device ====
{{PARAM|RunDevice|Run device like Easy-USB|string|""}}

{{PARAM|RunDeviceOpt|Run device option|string|""}}

== Command-line overwrite ==

The followings parameters can be overwrite from command-line parameter when the Build tool script is invoked:

{| class="wikitable"
! Overwrite syntax !! Config parameter !! Desc. !! Example
|-
| <tt>'''projname=<name>'''</tt> || <tt>ProjName</tt> || Set project name (without extension) || <tt>projname=mygame</tt>
|-
| <tt>'''target=<name>'''</tt> || <tt>Target</tt> || Set target name || <tt>target=DOS1</tt> (for MSX-DOS program)
|-
| <tt>'''machine=<name>'''</tt> || <tt>Machine</tt> || Set machine name || <tt>machine=2P</tt> (for MSX2+ machine)
|-
| <tt>'''romsize=<size>'''</tt> || <tt>ROMSize</tt> || Set ROM size (in KB) || <tt>romsize=256</tt> (for 256 KB mapped-ROM)
|-
| <tt>'''delay'''</tt> || <tt>ROMDelayBoot</tt> || Enable ROM delay boot ||
|-
| <tt>'''ramisr'''</tt> || <tt>InstallRAMISR</tt> || Install the RAM0 interrupt service routine (<tt>InstallRAMISR="RAM0_ISR"</tt>) ||
|-
| <tt>'''ramseg'''</tt> || <tt>InstallRAMISR</tt> || Install the RAM0 segment (<tt>InstallRAMISR="RAM0_SEGMENT"</tt>) ||
|-
| <tt>'''clean'''</tt> || <tt>DoClean</tt> || Clean all generated files ||
|-
| <tt>'''compile'''</tt> || <tt>DoCompile</tt> || Compile all source files ||
|-
| <tt>'''make'''</tt> || <tt>DoMake</tt> || Link all files together ||
|-
| <tt>'''package'''</tt> || <tt>DoPackage</tt> || Convert binary into target format ||
|-
| <tt>'''deploy'''</tt> || <tt>DoDeploy</tt> || Deploy final files into separate directory ||
|-
| <tt>'''run'''</tt> || <tt>DoRun</tt> || Run the built program with the selected emulator ||
|-
| <tt>'''rebuild'''</tt> || All <tt>DoXxx</tt> || Clean all generated files, then do all steps ||
|-
| <tt>'''define=<name>[:value]'''</tt> || <tt>CompileOpt</tt> || Define a compilation symbol (can be used multiple times) || <tt>define=MYDEF:123</tt>
|-
| <tt>'''help'''</tt> || || Display this command-line arguments list ||
|}

Note: For parameters that take a value, there should be no space before or after the equal sign '<tt>=</tt>'.

=== Example ===

==== Set target ====

The following command allows you to overwrite the build target from the command line.
E.g.: <tt>build DOS2</tt> (MSX-DOS2 application) or <tt>build ROM_48K</tt> (48 KB plain-ROM cartridge).
<syntaxhighlight lang="console">
..\..\tools\build\Node\node.exe ..\..\engine\script\js\build.js target=%1
</syntaxhighlight>

==== Transfert all parameters ====

It is recommended that you pass all command line parameters to the build script.
This allows you to fully configure your build sessions according to your needs.
Here is an example of a build.bat script:
<syntaxhighlight lang="console">
..\..\tools\build\Node\node.exe ..\..\engine\script\js\build.js %1 %2 %3 %4 %5 %6 %7 %8 %9
</syntaxhighlight>

== Misc ==

Previously, the Build tool was written in Windows batch format.
Here is a [[Batch to JS conversion guide|guide to convert the configuration files to use the new Build tool]].

⚠️ Old batch version of the build tool is no longer supported start from MSXgl 1.0.1 version. Please update your project configuration.

Build tool/BIOSReleaseEvent

2026-04-18T17:54:12Z

Aoineko: Created page with "Build tool option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switch out from page 0."

[[Build tool]] option '''BIOSReleaseEvent''' is used to add a callback function to be called just before BIOS is switch out from page 0.

Build tool

2026-04-18T17:53:08Z

Aoineko: /* Project */

The '''Build tool''' is the {{MSXGL}} script that will create your final program for MSX.

It is fully configurable by the user. For example, it is here that we can choose whether we want our game to be available in ROM, MSX-DOS or BASIC binary format. Or if our program should be MSX1 compatible or only MSX2+ for example.

The Build tool is written in JavaScript and executed via Node.js. All the programs needed to run the script are available in MSXgl and the user does not need to install anything.

Build tool is started from the project directory via a script that depends on the platform:
* On Windows, run <tt>build.bat</tt>,
* On Linux, run <tt>./build.sh</tt>.

See the <tt>example</tt> or <tt>template</tt> project for an actual use case.

== Configuration ==

The Build tool configuration's parameters are defined in the '''engine''' (<tt>engine/script/js/setup_global.js</tt>) and can be overwrite by the user at two levels:
* The '''default''' configuration (<tt>projects/default_config.js</tt>), commun for all the projects.
* The '''project''' configuration (<tt>projects/myProject/project_config.js</tt>), specific for a given project.

The value of the parameters redefined in a higher level replaces that of a lower level.

Some parameters can be overwrite as command-line parameters (see [[#Command-line overwrite|Command-line overwrite]] section).

The order of '''priority''' is: Command-line > Project config > Default config > Engine config.

== Build parameters ==

=== Stage ===
The build tool is divided into several stages that you can choose to activate or deactivate at will.

{{PARAM|DoClean|Clear all intermediate files and exit|boolean|false}}

{{PARAM|DoCompile|Compile all the project and engine source code. Generate all REL files|boolean|true}}

{{PARAM|DoMake|Link all the project and engine source code. Merge all REL into one IHX file|boolean|true}}

{{PARAM|DoPackage|Generate final binary file (boolean). Binarize the IHX file|boolean|true}}

{{PARAM|DoDeploy|Gathering of all files necessary for the program to work (boolean). Depends on the type of target|boolean|true}}

{{PARAM|DoRun|Start the program automatically at the end of the build|boolean|false}}

=== Path ===

{{PARAM|ProjDir|Project directory|string|}}

{{PARAM|OutDir|Intermediate files directory|string|`${ProjDir}out/`}}

{{PARAM|RootDir|MSXgl root directory|string|}}

{{PARAM|LibDir|Library directory|string|`${RootDir}engine/`}}

{{PARAM|ToolsDir|Tools directory|string|`${RootDir}tools/`}}

=== Tools ===

{{PARAM|SDCCPath|Path to SDCC tools chain|string|`${ToolsDir}sdcc/`}}

{{PARAM|Compiler|Path to the C compile program|string|`${SDCCPath}bin/sdcc`}}

{{PARAM|Assembler|Path to the assembler program|string|`${SDCCPath}bin/sdasz80`}}

{{PARAM|Linker|Path to the linker program|string|`${SDCCPath}bin/sdcc`}}

{{PARAM|MakeLib|Path to the program to generate lib file|string|`${SDCCPath}bin/sdar`}}

{{PARAM|Hex2Bin|Path to IHX to binary convertor|string|`${ToolsDir}MSXtk/bin/MSXhex`}}

{{PARAM|MSXDOS|Path to the MSX-DOS files|string|`${ToolsDir}build/DOS/`}}

{{PARAM|DskTool|Path to the tool to generate DSK file|string|`${ToolsDir}build/msxtar/msxtar`}}

{{PARAM|Emulator|Path to the emulator to launch the project|string|}}

=== Project ===

{{PARAM|ProjName|Project name. Will be use for output filename|string|}}

{{PARAM|ProjModules|List of project modules to build. If empty, ProjName will be added|array|}}

{{PARAM|ProjSegments|Project segments base name. ProjName will be used if not defined|string|}}

{{PARAM|LibModules|List of library modules to build|array|}}

{{PARAM|AddSources|Additional sources to be compiled and linked with the project|array|}}

{{PARAM|AddLibs|Additional extern library to be linked with the project|array|}}

{{PARAM|Machine|Target MSX machine version|string|"1"}}
<syntaxhighlight lang="js">
// - 1 MSX1
// - 2 MSX2
// - 12 MSX1 and 2 (multi support)
// - 2K Korean MSX2 (SC9 support)
// - 2P MSX2+
// - 22P MSX2 and 2+ (multi support)
// - 122P MSX1, 2 and 2+ (multi support)
// - 0 MSX0
// - TR MSX turbo R
// - 3 MSX3 (reserved)
</syntaxhighlight>
Multi support means that the application can use the features of all supported MSX generations. The user must detect the MSX version at runtime and adjust the program accordingly.

{{PARAM|Target|Target program format|string|"ROM_32K"}}
<syntaxhighlight lang="js">
// - BIN_DISK .bin BASIC binary program (starting at 8000h) on disk
// - BIN_TAPE .bin BASIC binary program (starting at 8000h) on tape
// - BIN_USR .bin BASIC USR binary driver (starting at C000h)
// - DOS1 .com MSX-DOS 1 program (starting at 0100h)
// - DOS2 .com MSX-DOS 2 program (starting at 0100h)
// - DOS0 .com Direct program boot from disk (starting at 0100h)
// - ROM_8K .rom 8 KB ROM in page 1 (4000h ~ 5FFFh)
// - ROM_8K_P2 .rom 8 KB ROM in page 2 (8000h ~ 9FFFh)
// - ROM_16K .rom 16 KB ROM in page 1 (4000h ~ 7FFFh)
// - ROM_16K_P2 .rom 16 KB ROM in page 2 (8000h ~ BFFFh)
// - ROM_32K .rom 32 KB ROM in page 1&2 (4000h ~ BFFFh)
// - ROM_48K .rom 48 KB ROM in page 0-2 (0000h ~ BFFFh)
// - ROM_48K_ISR .rom 48 KB ROM in page 0-2 (0000h ~ BFFFh) with ISR replacement
// - ROM_64K .rom 64 KB ROM in page 0-3 (0000h ~ FFFFh)
// - ROM_64K_ISR .rom 64 KB ROM in page 0-3 (0000h ~ FFFFh) with ISR replacement
// - ROM_ASCII8 .rom ASCII-8: 8 KB segments for a total of 64 KB to 2 MB
// - ROM_ASCII16 .rom ASCII-16: 16 KB segments for a total of 64 KB to 4 MB
// - ROM_KONAMI .rom Konami MegaROM (aka Konami4): 8 KB segments for a total of 64 KB to 2 MB
// - ROM_KONAMI_SCC .rom Konami MegaROM SCC (aka Konami5): 8 KB segments for a total of 64 KB to 2 MB
// - ROM_NEO8 .rom NEO-8: 8 KB segments for a total of 1 MB to 32 MB
// - ROM_NEO16 .rom NEO-16: 16 KB segments for a total of 1 MB to 64 MB
// - ROM_YAMANOOTO .rom Yamanooto: 8 KB segments for a total up to 8 MB
// - ROM_ASCII16X .rom ASCII16-X: 16 KB segments for a total up to 64 MB
// - RAW .bin Raw binary code and data to be compiled at a given address
// - LIB .lib C library to be included in other project
</syntaxhighlight>
More detail: [[Targets]]

{{PARAM|ROMSize|ROM mapper total size in KB. Must be a multiple of 8 or 16 depending on the mapper type (from 64 to 4096)|number|128}}

{{PARAM|ROMMainSegments|Number of segments in the main program of a mapped-ROM. 0 means 'number of segments to fill 32 KB of ROM|number|0}}

{{PARAM|ROMSkipBoot|Check for ROM boot skipping if a given key is pressed|boolean|false}}

{{PARAM|ROMSkipBootKey|The key to be check for ROM boot skipping. Key must be from keyboard row #7|string|"ESC"}}
<syntaxhighlight lang="js">
// - F4
// - F5
// - ESC
// - TAB
// - STOP
// - BS
// - SELECT
// - RETURN
</syntaxhighlight>

{{PARAM|ROMDelayBoot|Postpone the ROM startup to let the other ROMs initialize like Disk controller or Network cartridge|boolean|false}}

{{PARAM|AddROMSignature|Add a ROM signature to help flasher and emulator to detect the ROM type properly|boolean|false}}

{{PARAM|InstallRAMISR|Select RAM in slot 0 and install ISR and optional code there. For MSX with at least 64 KB of RAM|string|"RAM0_NONE"}}
<syntaxhighlight lang="js">
// - RAM0_NONE Don't install anything in RAM
// - RAM0_ISR Install only ISR
// - RAM0_SEGMENT Install ISR and segment data (for mapped-ROM)
</syntaxhighlight>
For mode detail about usage of RAM0_SEGMENT, check [[Build tool/InstallRAMISR|this document]].

{{PARAM|CustomISR|Type of custom ISR to install. ISR is install in RAM or ROM depending on Target and InstallRAMISR parameters|string|"VBLANK"}}
<syntaxhighlight lang="js">
// - NONE No ISR
// - ALL Handle all interruptions
// - VBLANK V-blank handler
// - VHBLANK V-blank and h-blank handler (V9938 or V9958)
// - V9990 V-blank, h-blank and command end handler (V9990)
</syntaxhighlight>
Depending on the selected ISR, some functions must be provided by the user:
<syntaxhighlight lang="c">
// CustomISR = "ALL"
VDP_InterruptHandler(); // All interrupt

// CustomISR = "VBLANK"
VDP_InterruptHandler(); // V-blank interrupt

// CustomISR = "VHBLANK"
VDP_InterruptHandler(); // V-blank interrupt
VDP_HBlankHandler(); // H-blank interrupt

// CustomISR = "V9990"
V9_InterruptVBlank(); // V-blank interrupt
V9_InterruptHBlank(); // H-blank interrupt
V9_InterruptCommand(); // Command end interrupt
</syntaxhighlight>

{{PARAM|BIOSReleaseEvent|Event called before BIOS is released. For target format that switch out BIOS from page 0.|boolean|false}}
More detail: [[Build tool/BIOSReleaseEvent]]

{{PARAM|CheckVersion|Add code to check MSX version at program startup. Works for ROM and BASIC program.|boolean|false}}

{{PARAM|BankedCall|Use automatic banked call and trampoline functions (for mapped ROM)|boolean|false}}

{{PARAM|ForceCodeAddr|Overwrite code starting address. For example. 0xE0000 for a driver in RAM|number|0}}

{{PARAM|ForceRamAddr|Overwrite RAM starting address. For example. 0xE0000 for 8K RAM machine|number|0}}

{{PARAM|RawFiles|List of raw data files to be added to the final binary|array|}}
Raw files can be added to final binary by defining 3 types of position: <tt>offset</tt>, <tt>segment</tt> or <tt>page</tt>.
<syntaxhighlight lang="js">
// Sample example
RawFiles = [
{ offset: 0x10000, file: "file1.bin" }, // Offset from final binary start
{ segment: 7, file: "file2.bin" }, // Segment number for mapped-ROM
{ page: 0, file: "file.bin" }, // Page number (16 KB) in the final binary
];
</syntaxhighlight>
Notes:
* If the <tt>RawFiles</tt> table is not empty, the Build tool will generate a definition header file (<tt>myproject_rawdef.h</tt>) with information to access the raw binary data from code.
* More than one file can be add to the same page or mapper segment. In this case, data will be concatenated in the table order, and definition header file (see above) is needed to know the offset (relative to page / segment) where data is located.
* When using page 0 (0x0000~0x3FFF), data will be placed from address 0x0100 (after the area reserved for the ISR).

{{PARAM|DiskFiles|List of data files to copy to disk|array|}}

{{PARAM|DiskSize|Size of the final disk (.DSK file). Can be "360K" or "720K"|string|"720K"}}

{{PARAM|DOSParseArg|Parse MSX-DOS command-line arguments|boolean|true}}

=== Signature ===
{{PARAM|AppSignature|Add application signature to binary data|boolean|false}}

{{PARAM|AppCompany|Application company. Can be 2 character string or 16-bits integer|string/number|"GL"}}

{{PARAM|AppID|Application ID. Can be 2 character string or 16-bits integer (0~65535)|string/number|0}}

{{PARAM|AppExtra|Application extra data. Comma-separated bytes starting with data size|array|}}

Note: See [[AppSignature]] and [[AppExtra]] for more details.

=== Make ===

{{PARAM|BuildLibrary|Force to generate MSXgl static library even if 'msxgl.lib' already exist|bolean|true}}

{{PARAM|Debug|Prepare program for debug|boolean|false}}

{{PARAM|DebugSymbols|Move debug symbols to deployement folder|boolean|false}}

{{PARAM|AllowUndocumented|Allow compiler to generate undocumented Z80 instructions|boolean|true}}

{{PARAM|AsmOptim|Assembler code optimizer ⚠️ WIP|string|"None"}}
<syntaxhighlight lang="js">
// - None
// - Peep SDCC peep hole otpimizer
// - MDL MDL z80 otpimizer
</syntaxhighlight>

{{PARAM|Optim|Code optimization priority|string|"Speed"}}
<syntaxhighlight lang="js">
// - Default
// - Speed
// - Size
</syntaxhighlight>

{{PARAM|CompileComplexity|Compile complexity. The higher the most optimized but the slowest to compile. Can be one of the predefine name or a integer value.|string/integer|"Default"}}
<syntaxhighlight lang="js">
// - Fast 2000
// - Default 3000
// - Optimized 50000
// - Ultra 200000
// - Insane 10000000
</syntaxhighlight>

{{PARAM|CompileOpt|Additionnal compilation flag|string|}}

{{PARAM|CompileSkipOld|Skip file if compiled data (REL) is newer than the source code|boolean|false}}

{{PARAM|LinkOpt|Additionnal link options|string|}}

{{PARAM|BuildVersion|Automatic increment of build version in a header file|boolean|false}}

{{PARAM|PackSegments|Package all segments into a lib file to reduce the number of files to link|boolean|false}}

{{PARAM|GenCompileDB|Generate Clang compatible Compilation database|boolean|false}}

{{PARAM|HexBinOpt|Additionnal options of Hex to Binary convertor|string|""}}

{{PARAM|PreBuildScripts|Command lines to be executed before the build process|array|[]}}

{{PARAM|PostBuildScripts|Command lines to be executed after the build process|array|[]}}

=== Localization ===

{{PARAM|LocFiles|List files to be localized|array|}}

{{PARAM|LocOutput|Localization output filename|string|"localization.h"}}

{{PARAM|LocStruct|Localization structure name|string|"g_LocData"}}

{{PARAM|LocSplitDef|Split socalization data and definitions in different files|boolean|false}}

For example:
<syntaxhighlight lang="js">
//-- List files to be localized (array)
LocFiles = [ "translate_en.ini", "translate_fr.ini", "translate_ja.ini" ];

//-- Localization output filename (string)
LocOutput = "data/translate.h";

//-- Localization structure name (string)
LocStruct = "g_TransData";

//-- Split socalization data and definitions in different files (boolean)
LocSplitDef = true;
</syntaxhighlight>

=== Build Tool ===

{{PARAM|Verbose|Activate verbose mode and get more build information|boolean|false}}

{{PARAM|LogStdout|Output build information to the standard console|boolean|true}}

{{PARAM|LogFile|Output build information to a log file|boolean|false}}

{{PARAM|LogFileName|Name of the log file|string|"log_YYYYMMDD_HHMMSS.txt"}}

=== Analyzer ===

{{PARAM|Analyzer|Execute compiler analyzer|boolean|true}}

{{PARAM|AnalyzerOutput|Analyzer output selection|string|Both}}
<syntaxhighlight lang="js">
// - Console Output to termial console
// - File Output to file
// - Both Output to file and termial console (default)
</syntaxhighlight>

{{PARAM|AnalyzerReport|Analyzer report elements|string|ASMCV}}
<syntaxhighlight lang="js">
// - [A] Report areas
// - [S] Report segments
// - [M] Report modules
// - [C] Report code symbols
// - [V] Report variable symbols
</syntaxhighlight>

{{PARAM|AnalyzerSort|Analyzer report sorting|string|Size}}
<syntaxhighlight lang="js">
// - None No sorting (MAP file order)
// - Alpha Alphanumeric sorting
// - Size Size sorting (default)
</syntaxhighlight>

{{PARAM|AnalyzerCSV|Export analyzer data to CSV file|boolean|false}}

{{PARAM|AnalyzerSeparator|Analyzer CSV file separator|string|","}}

=== Package ===

{{PARAM|Standalone|Should the build tool create a standalone package?|boolean|false}}

Note: Package is created in a <tt>/package/</tt> folder at the root of the project.

=== Emulator ===

==== General ====
{{PARAM|EmulMachine|Force the MSX version of the emulated machine|boolean|true}}

{{PARAM|Emul60Hz|Force the emulated machine to be at 60 Hz|boolean|false}}

{{PARAM|EmulFullScreen|Force the emulator to start in fullscreen mode|boolean|false}}

{{PARAM|EmulMute|Disable emulator sound|boolean|false}}

{{PARAM|EmulDebug|Start emulator debugger with program launch|boolean|false}}

{{PARAM|EmulTurbo|Start emulator in turbo mode|boolean|false}}

{{PARAM|EmulExtraParam|Emulator extra parameters to be add to command-line. Emulator sotfware specific|string|}}

==== Extensions ====
{{PARAM|EmulSCC|Add SCC extension|boolean|false}}

{{PARAM|EmulMSXMusic|Add MSX-Music extension|boolean|false}}

{{PARAM|EmulMSXAudio|Add MSX-Audio extension|boolean|false}}

{{PARAM|EmulOPL4|Add OPL4 extension|boolean|false}}

{{PARAM|EmulPSG2|Add second PSG extension|boolean|false}}

{{PARAM|EmulV9990|Add V9990 video-chip extension|boolean|false}}

{{PARAM|EmulRAM|Add mapped-RAM extension|boolean|false}}

Note: The biggest available RAM extension will be selected (4 MB if supported)

==== Input ====
{{PARAM|EmulPortA|Plug a virtual device into the joystick port A|string|}}
<syntaxhighlight lang="js">
// - Joystick
// - Mouse
// - Paddle
// - JoyMega
// - NinjaTap
</syntaxhighlight>

{{PARAM|EmulPortB|Plug a virtual device into the joystick port B|string|}}
<syntaxhighlight lang="js">
// - Joystick
// - Mouse
// - Paddle
// - JoyMega
// - NinjaTap
</syntaxhighlight>

==== Run device ====
{{PARAM|RunDevice|Run device like Easy-USB|string|""}}

{{PARAM|RunDeviceOpt|Run device option|string|""}}

== Command-line overwrite ==

The followings parameters can be overwrite from command-line parameter when the Build tool script is invoked:

{| class="wikitable"
! Overwrite syntax !! Config parameter !! Desc. !! Example
|-
| <tt>'''projname=<name>'''</tt> || <tt>ProjName</tt> || Set project name (without extension) || <tt>projname=mygame</tt>
|-
| <tt>'''target=<name>'''</tt> || <tt>Target</tt> || Set target name || <tt>target=DOS1</tt> (for MSX-DOS program)
|-
| <tt>'''machine=<name>'''</tt> || <tt>Machine</tt> || Set machine name || <tt>machine=2P</tt> (for MSX2+ machine)
|-
| <tt>'''romsize=<size>'''</tt> || <tt>ROMSize</tt> || Set ROM size (in KB) || <tt>romsize=256</tt> (for 256 KB mapped-ROM)
|-
| <tt>'''delay'''</tt> || <tt>ROMDelayBoot</tt> || Enable ROM delay boot ||
|-
| <tt>'''ramisr'''</tt> || <tt>InstallRAMISR</tt> || Install the RAM0 interrupt service routine (<tt>InstallRAMISR="RAM0_ISR"</tt>) ||
|-
| <tt>'''ramseg'''</tt> || <tt>InstallRAMISR</tt> || Install the RAM0 segment (<tt>InstallRAMISR="RAM0_SEGMENT"</tt>) ||
|-
| <tt>'''clean'''</tt> || <tt>DoClean</tt> || Clean all generated files ||
|-
| <tt>'''compile'''</tt> || <tt>DoCompile</tt> || Compile all source files ||
|-
| <tt>'''make'''</tt> || <tt>DoMake</tt> || Link all files together ||
|-
| <tt>'''package'''</tt> || <tt>DoPackage</tt> || Convert binary into target format ||
|-
| <tt>'''deploy'''</tt> || <tt>DoDeploy</tt> || Deploy final files into separate directory ||
|-
| <tt>'''run'''</tt> || <tt>DoRun</tt> || Run the built program with the selected emulator ||
|-
| <tt>'''rebuild'''</tt> || All <tt>DoXxx</tt> || Clean all generated files, then do all steps ||
|-
| <tt>'''define=<name>[:value]'''</tt> || <tt>CompileOpt</tt> || Define a compilation symbol (can be used multiple times) || <tt>define=MYDEF:123</tt>
|-
| <tt>'''help'''</tt> || || Display this command-line arguments list ||
|}

Note: For parameters that take a value, there should be no space before or after the equal sign '<tt>=</tt>'.

=== Example ===

==== Set target ====

The following command allows you to overwrite the build target from the command line.
E.g.: <tt>build DOS2</tt> (MSX-DOS2 application) or <tt>build ROM_48K</tt> (48 KB plain-ROM cartridge).
<syntaxhighlight lang="console">
..\..\tools\build\Node\node.exe ..\..\engine\script\js\build.js target=%1
</syntaxhighlight>

==== Transfert all parameters ====

It is recommended that you pass all command line parameters to the build script.
This allows you to fully configure your build sessions according to your needs.
Here is an example of a build.bat script:
<syntaxhighlight lang="console">
..\..\tools\build\Node\node.exe ..\..\engine\script\js\build.js %1 %2 %3 %4 %5 %6 %7 %8 %9
</syntaxhighlight>

== Misc ==

Previously, the Build tool was written in Windows batch format.
Here is a [[Batch to JS conversion guide|guide to convert the configuration files to use the new Build tool]].

⚠️ Old batch version of the build tool is no longer supported start from MSXgl 1.0.1 version. Please update your project configuration.

Build tool

2026-04-18T17:52:21Z

Aoineko: /* Project */

The '''Build tool''' is the {{MSXGL}} script that will create your final program for MSX.

It is fully configurable by the user. For example, it is here that we can choose whether we want our game to be available in ROM, MSX-DOS or BASIC binary format. Or if our program should be MSX1 compatible or only MSX2+ for example.

The Build tool is written in JavaScript and executed via Node.js. All the programs needed to run the script are available in MSXgl and the user does not need to install anything.

Build tool is started from the project directory via a script that depends on the platform:
* On Windows, run <tt>build.bat</tt>,
* On Linux, run <tt>./build.sh</tt>.

See the <tt>example</tt> or <tt>template</tt> project for an actual use case.

== Configuration ==

The Build tool configuration's parameters are defined in the '''engine''' (<tt>engine/script/js/setup_global.js</tt>) and can be overwrite by the user at two levels:
* The '''default''' configuration (<tt>projects/default_config.js</tt>), commun for all the projects.
* The '''project''' configuration (<tt>projects/myProject/project_config.js</tt>), specific for a given project.

The value of the parameters redefined in a higher level replaces that of a lower level.

Some parameters can be overwrite as command-line parameters (see [[#Command-line overwrite|Command-line overwrite]] section).

The order of '''priority''' is: Command-line > Project config > Default config > Engine config.

== Build parameters ==

=== Stage ===
The build tool is divided into several stages that you can choose to activate or deactivate at will.

{{PARAM|DoClean|Clear all intermediate files and exit|boolean|false}}

{{PARAM|DoCompile|Compile all the project and engine source code. Generate all REL files|boolean|true}}

{{PARAM|DoMake|Link all the project and engine source code. Merge all REL into one IHX file|boolean|true}}

{{PARAM|DoPackage|Generate final binary file (boolean). Binarize the IHX file|boolean|true}}

{{PARAM|DoDeploy|Gathering of all files necessary for the program to work (boolean). Depends on the type of target|boolean|true}}

{{PARAM|DoRun|Start the program automatically at the end of the build|boolean|false}}

=== Path ===

{{PARAM|ProjDir|Project directory|string|}}

{{PARAM|OutDir|Intermediate files directory|string|`${ProjDir}out/`}}

{{PARAM|RootDir|MSXgl root directory|string|}}

{{PARAM|LibDir|Library directory|string|`${RootDir}engine/`}}

{{PARAM|ToolsDir|Tools directory|string|`${RootDir}tools/`}}

=== Tools ===

{{PARAM|SDCCPath|Path to SDCC tools chain|string|`${ToolsDir}sdcc/`}}

{{PARAM|Compiler|Path to the C compile program|string|`${SDCCPath}bin/sdcc`}}

{{PARAM|Assembler|Path to the assembler program|string|`${SDCCPath}bin/sdasz80`}}

{{PARAM|Linker|Path to the linker program|string|`${SDCCPath}bin/sdcc`}}

{{PARAM|MakeLib|Path to the program to generate lib file|string|`${SDCCPath}bin/sdar`}}

{{PARAM|Hex2Bin|Path to IHX to binary convertor|string|`${ToolsDir}MSXtk/bin/MSXhex`}}

{{PARAM|MSXDOS|Path to the MSX-DOS files|string|`${ToolsDir}build/DOS/`}}

{{PARAM|DskTool|Path to the tool to generate DSK file|string|`${ToolsDir}build/msxtar/msxtar`}}

{{PARAM|Emulator|Path to the emulator to launch the project|string|}}

=== Project ===

{{PARAM|ProjName|Project name. Will be use for output filename|string|}}

{{PARAM|ProjModules|List of project modules to build. If empty, ProjName will be added|array|}}

{{PARAM|ProjSegments|Project segments base name. ProjName will be used if not defined|string|}}

{{PARAM|LibModules|List of library modules to build|array|}}

{{PARAM|AddSources|Additional sources to be compiled and linked with the project|array|}}

{{PARAM|AddLibs|Additional extern library to be linked with the project|array|}}

{{PARAM|Machine|Target MSX machine version|string|"1"}}
<syntaxhighlight lang="js">
// - 1 MSX1
// - 2 MSX2
// - 12 MSX1 and 2 (multi support)
// - 2K Korean MSX2 (SC9 support)
// - 2P MSX2+
// - 22P MSX2 and 2+ (multi support)
// - 122P MSX1, 2 and 2+ (multi support)
// - 0 MSX0
// - TR MSX turbo R
// - 3 MSX3 (reserved)
</syntaxhighlight>
Multi support means that the application can use the features of all supported MSX generations. The user must detect the MSX version at runtime and adjust the program accordingly.

{{PARAM|Target|Target program format|string|"ROM_32K"}}
<syntaxhighlight lang="js">
// - BIN_DISK .bin BASIC binary program (starting at 8000h) on disk
// - BIN_TAPE .bin BASIC binary program (starting at 8000h) on tape
// - BIN_USR .bin BASIC USR binary driver (starting at C000h)
// - DOS1 .com MSX-DOS 1 program (starting at 0100h)
// - DOS2 .com MSX-DOS 2 program (starting at 0100h)
// - DOS0 .com Direct program boot from disk (starting at 0100h)
// - ROM_8K .rom 8 KB ROM in page 1 (4000h ~ 5FFFh)
// - ROM_8K_P2 .rom 8 KB ROM in page 2 (8000h ~ 9FFFh)
// - ROM_16K .rom 16 KB ROM in page 1 (4000h ~ 7FFFh)
// - ROM_16K_P2 .rom 16 KB ROM in page 2 (8000h ~ BFFFh)
// - ROM_32K .rom 32 KB ROM in page 1&2 (4000h ~ BFFFh)
// - ROM_48K .rom 48 KB ROM in page 0-2 (0000h ~ BFFFh)
// - ROM_48K_ISR .rom 48 KB ROM in page 0-2 (0000h ~ BFFFh) with ISR replacement
// - ROM_64K .rom 64 KB ROM in page 0-3 (0000h ~ FFFFh)
// - ROM_64K_ISR .rom 64 KB ROM in page 0-3 (0000h ~ FFFFh) with ISR replacement
// - ROM_ASCII8 .rom ASCII-8: 8 KB segments for a total of 64 KB to 2 MB
// - ROM_ASCII16 .rom ASCII-16: 16 KB segments for a total of 64 KB to 4 MB
// - ROM_KONAMI .rom Konami MegaROM (aka Konami4): 8 KB segments for a total of 64 KB to 2 MB
// - ROM_KONAMI_SCC .rom Konami MegaROM SCC (aka Konami5): 8 KB segments for a total of 64 KB to 2 MB
// - ROM_NEO8 .rom NEO-8: 8 KB segments for a total of 1 MB to 32 MB
// - ROM_NEO16 .rom NEO-16: 16 KB segments for a total of 1 MB to 64 MB
// - ROM_YAMANOOTO .rom Yamanooto: 8 KB segments for a total up to 8 MB
// - ROM_ASCII16X .rom ASCII16-X: 16 KB segments for a total up to 64 MB
// - RAW .bin Raw binary code and data to be compiled at a given address
// - LIB .lib C library to be included in other project
</syntaxhighlight>
More detail: [[Targets]]

{{PARAM|ROMSize|ROM mapper total size in KB. Must be a multiple of 8 or 16 depending on the mapper type (from 64 to 4096)|number|128}}

{{PARAM|ROMMainSegments|Number of segments in the main program of a mapped-ROM. 0 means 'number of segments to fill 32 KB of ROM|number|0}}

{{PARAM|ROMSkipBoot|Check for ROM boot skipping if a given key is pressed|boolean|false}}

{{PARAM|ROMSkipBootKey|The key to be check for ROM boot skipping. Key must be from keyboard row #7|string|"ESC"}}
<syntaxhighlight lang="js">
// - F4
// - F5
// - ESC
// - TAB
// - STOP
// - BS
// - SELECT
// - RETURN
</syntaxhighlight>

{{PARAM|ROMDelayBoot|Postpone the ROM startup to let the other ROMs initialize like Disk controller or Network cartridge|boolean|false}}

{{PARAM|AddROMSignature|Add a ROM signature to help flasher and emulator to detect the ROM type properly|boolean|false}}

{{PARAM|InstallRAMISR|Select RAM in slot 0 and install ISR and optional code there. For MSX with at least 64 KB of RAM|string|"RAM0_NONE"}}
<syntaxhighlight lang="js">
// - RAM0_NONE Don't install anything in RAM
// - RAM0_ISR Install only ISR
// - RAM0_SEGMENT Install ISR and segment data (for mapped-ROM)
</syntaxhighlight>
For mode detail about usage of RAM0_SEGMENT, check [[Build tool/InstallRAMISR|this document]].

{{PARAM|CustomISR|Type of custom ISR to install. ISR is install in RAM or ROM depending on Target and InstallRAMISR parameters|string|"VBLANK"}}
<syntaxhighlight lang="js">
// - NONE No ISR
// - ALL Handle all interruptions
// - VBLANK V-blank handler
// - VHBLANK V-blank and h-blank handler (V9938 or V9958)
// - V9990 V-blank, h-blank and command end handler (V9990)
</syntaxhighlight>
Depending on the selected ISR, some functions must be provided by the user:
<syntaxhighlight lang="c">
// CustomISR = "ALL"
VDP_InterruptHandler(); // All interrupt

// CustomISR = "VBLANK"
VDP_InterruptHandler(); // V-blank interrupt

// CustomISR = "VHBLANK"
VDP_InterruptHandler(); // V-blank interrupt
VDP_HBlankHandler(); // H-blank interrupt

// CustomISR = "V9990"
V9_InterruptVBlank(); // V-blank interrupt
V9_InterruptHBlank(); // H-blank interrupt
V9_InterruptCommand(); // Command end interrupt
</syntaxhighlight>

{{PARAM|BIOSReleaseEvent[Event called before BIOS is released. For target format that switch out BIOS from page 0.|boolean|false}}
More detail: [[Build tool/BIOSReleaseEvent]]

{{PARAM|CheckVersion|Add code to check MSX version at program startup. Works for ROM and BASIC program.|boolean|false}}

{{PARAM|BankedCall|Use automatic banked call and trampoline functions (for mapped ROM)|boolean|false}}

{{PARAM|ForceCodeAddr|Overwrite code starting address. For example. 0xE0000 for a driver in RAM|number|0}}

{{PARAM|ForceRamAddr|Overwrite RAM starting address. For example. 0xE0000 for 8K RAM machine|number|0}}

{{PARAM|RawFiles|List of raw data files to be added to the final binary|array|}}
Raw files can be added to final binary by defining 3 types of position: <tt>offset</tt>, <tt>segment</tt> or <tt>page</tt>.
<syntaxhighlight lang="js">
// Sample example
RawFiles = [
{ offset: 0x10000, file: "file1.bin" }, // Offset from final binary start
{ segment: 7, file: "file2.bin" }, // Segment number for mapped-ROM
{ page: 0, file: "file.bin" }, // Page number (16 KB) in the final binary
];
</syntaxhighlight>
Notes:
* If the <tt>RawFiles</tt> table is not empty, the Build tool will generate a definition header file (<tt>myproject_rawdef.h</tt>) with information to access the raw binary data from code.
* More than one file can be add to the same page or mapper segment. In this case, data will be concatenated in the table order, and definition header file (see above) is needed to know the offset (relative to page / segment) where data is located.
* When using page 0 (0x0000~0x3FFF), data will be placed from address 0x0100 (after the area reserved for the ISR).

{{PARAM|DiskFiles|List of data files to copy to disk|array|}}

{{PARAM|DiskSize|Size of the final disk (.DSK file). Can be "360K" or "720K"|string|"720K"}}

{{PARAM|DOSParseArg|Parse MSX-DOS command-line arguments|boolean|true}}

=== Signature ===
{{PARAM|AppSignature|Add application signature to binary data|boolean|false}}

{{PARAM|AppCompany|Application company. Can be 2 character string or 16-bits integer|string/number|"GL"}}

{{PARAM|AppID|Application ID. Can be 2 character string or 16-bits integer (0~65535)|string/number|0}}

{{PARAM|AppExtra|Application extra data. Comma-separated bytes starting with data size|array|}}

Note: See [[AppSignature]] and [[AppExtra]] for more details.

=== Make ===

{{PARAM|BuildLibrary|Force to generate MSXgl static library even if 'msxgl.lib' already exist|bolean|true}}

{{PARAM|Debug|Prepare program for debug|boolean|false}}

{{PARAM|DebugSymbols|Move debug symbols to deployement folder|boolean|false}}

{{PARAM|AllowUndocumented|Allow compiler to generate undocumented Z80 instructions|boolean|true}}

{{PARAM|AsmOptim|Assembler code optimizer ⚠️ WIP|string|"None"}}
<syntaxhighlight lang="js">
// - None
// - Peep SDCC peep hole otpimizer
// - MDL MDL z80 otpimizer
</syntaxhighlight>

{{PARAM|Optim|Code optimization priority|string|"Speed"}}
<syntaxhighlight lang="js">
// - Default
// - Speed
// - Size
</syntaxhighlight>

{{PARAM|CompileComplexity|Compile complexity. The higher the most optimized but the slowest to compile. Can be one of the predefine name or a integer value.|string/integer|"Default"}}
<syntaxhighlight lang="js">
// - Fast 2000
// - Default 3000
// - Optimized 50000
// - Ultra 200000
// - Insane 10000000
</syntaxhighlight>

{{PARAM|CompileOpt|Additionnal compilation flag|string|}}

{{PARAM|CompileSkipOld|Skip file if compiled data (REL) is newer than the source code|boolean|false}}

{{PARAM|LinkOpt|Additionnal link options|string|}}

{{PARAM|BuildVersion|Automatic increment of build version in a header file|boolean|false}}

{{PARAM|PackSegments|Package all segments into a lib file to reduce the number of files to link|boolean|false}}

{{PARAM|GenCompileDB|Generate Clang compatible Compilation database|boolean|false}}

{{PARAM|HexBinOpt|Additionnal options of Hex to Binary convertor|string|""}}

{{PARAM|PreBuildScripts|Command lines to be executed before the build process|array|[]}}

{{PARAM|PostBuildScripts|Command lines to be executed after the build process|array|[]}}

=== Localization ===

{{PARAM|LocFiles|List files to be localized|array|}}

{{PARAM|LocOutput|Localization output filename|string|"localization.h"}}

{{PARAM|LocStruct|Localization structure name|string|"g_LocData"}}

{{PARAM|LocSplitDef|Split socalization data and definitions in different files|boolean|false}}

For example:
<syntaxhighlight lang="js">
//-- List files to be localized (array)
LocFiles = [ "translate_en.ini", "translate_fr.ini", "translate_ja.ini" ];

//-- Localization output filename (string)
LocOutput = "data/translate.h";

//-- Localization structure name (string)
LocStruct = "g_TransData";

//-- Split socalization data and definitions in different files (boolean)
LocSplitDef = true;
</syntaxhighlight>

=== Build Tool ===

{{PARAM|Verbose|Activate verbose mode and get more build information|boolean|false}}

{{PARAM|LogStdout|Output build information to the standard console|boolean|true}}

{{PARAM|LogFile|Output build information to a log file|boolean|false}}

{{PARAM|LogFileName|Name of the log file|string|"log_YYYYMMDD_HHMMSS.txt"}}

=== Analyzer ===

{{PARAM|Analyzer|Execute compiler analyzer|boolean|true}}

{{PARAM|AnalyzerOutput|Analyzer output selection|string|Both}}
<syntaxhighlight lang="js">
// - Console Output to termial console
// - File Output to file
// - Both Output to file and termial console (default)
</syntaxhighlight>

{{PARAM|AnalyzerReport|Analyzer report elements|string|ASMCV}}
<syntaxhighlight lang="js">
// - [A] Report areas
// - [S] Report segments
// - [M] Report modules
// - [C] Report code symbols
// - [V] Report variable symbols
</syntaxhighlight>

{{PARAM|AnalyzerSort|Analyzer report sorting|string|Size}}
<syntaxhighlight lang="js">
// - None No sorting (MAP file order)
// - Alpha Alphanumeric sorting
// - Size Size sorting (default)
</syntaxhighlight>

{{PARAM|AnalyzerCSV|Export analyzer data to CSV file|boolean|false}}

{{PARAM|AnalyzerSeparator|Analyzer CSV file separator|string|","}}

=== Package ===

{{PARAM|Standalone|Should the build tool create a standalone package?|boolean|false}}

Note: Package is created in a <tt>/package/</tt> folder at the root of the project.

=== Emulator ===

==== General ====
{{PARAM|EmulMachine|Force the MSX version of the emulated machine|boolean|true}}

{{PARAM|Emul60Hz|Force the emulated machine to be at 60 Hz|boolean|false}}

{{PARAM|EmulFullScreen|Force the emulator to start in fullscreen mode|boolean|false}}

{{PARAM|EmulMute|Disable emulator sound|boolean|false}}

{{PARAM|EmulDebug|Start emulator debugger with program launch|boolean|false}}

{{PARAM|EmulTurbo|Start emulator in turbo mode|boolean|false}}

{{PARAM|EmulExtraParam|Emulator extra parameters to be add to command-line. Emulator sotfware specific|string|}}

==== Extensions ====
{{PARAM|EmulSCC|Add SCC extension|boolean|false}}

{{PARAM|EmulMSXMusic|Add MSX-Music extension|boolean|false}}

{{PARAM|EmulMSXAudio|Add MSX-Audio extension|boolean|false}}

{{PARAM|EmulOPL4|Add OPL4 extension|boolean|false}}

{{PARAM|EmulPSG2|Add second PSG extension|boolean|false}}

{{PARAM|EmulV9990|Add V9990 video-chip extension|boolean|false}}

{{PARAM|EmulRAM|Add mapped-RAM extension|boolean|false}}

Note: The biggest available RAM extension will be selected (4 MB if supported)

==== Input ====
{{PARAM|EmulPortA|Plug a virtual device into the joystick port A|string|}}
<syntaxhighlight lang="js">
// - Joystick
// - Mouse
// - Paddle
// - JoyMega
// - NinjaTap
</syntaxhighlight>

{{PARAM|EmulPortB|Plug a virtual device into the joystick port B|string|}}
<syntaxhighlight lang="js">
// - Joystick
// - Mouse
// - Paddle
// - JoyMega
// - NinjaTap
</syntaxhighlight>

==== Run device ====
{{PARAM|RunDevice|Run device like Easy-USB|string|""}}

{{PARAM|RunDeviceOpt|Run device option|string|""}}

== Command-line overwrite ==

The followings parameters can be overwrite from command-line parameter when the Build tool script is invoked:

{| class="wikitable"
! Overwrite syntax !! Config parameter !! Desc. !! Example
|-
| <tt>'''projname=<name>'''</tt> || <tt>ProjName</tt> || Set project name (without extension) || <tt>projname=mygame</tt>
|-
| <tt>'''target=<name>'''</tt> || <tt>Target</tt> || Set target name || <tt>target=DOS1</tt> (for MSX-DOS program)
|-
| <tt>'''machine=<name>'''</tt> || <tt>Machine</tt> || Set machine name || <tt>machine=2P</tt> (for MSX2+ machine)
|-
| <tt>'''romsize=<size>'''</tt> || <tt>ROMSize</tt> || Set ROM size (in KB) || <tt>romsize=256</tt> (for 256 KB mapped-ROM)
|-
| <tt>'''delay'''</tt> || <tt>ROMDelayBoot</tt> || Enable ROM delay boot ||
|-
| <tt>'''ramisr'''</tt> || <tt>InstallRAMISR</tt> || Install the RAM0 interrupt service routine (<tt>InstallRAMISR="RAM0_ISR"</tt>) ||
|-
| <tt>'''ramseg'''</tt> || <tt>InstallRAMISR</tt> || Install the RAM0 segment (<tt>InstallRAMISR="RAM0_SEGMENT"</tt>) ||
|-
| <tt>'''clean'''</tt> || <tt>DoClean</tt> || Clean all generated files ||
|-
| <tt>'''compile'''</tt> || <tt>DoCompile</tt> || Compile all source files ||
|-
| <tt>'''make'''</tt> || <tt>DoMake</tt> || Link all files together ||
|-
| <tt>'''package'''</tt> || <tt>DoPackage</tt> || Convert binary into target format ||
|-
| <tt>'''deploy'''</tt> || <tt>DoDeploy</tt> || Deploy final files into separate directory ||
|-
| <tt>'''run'''</tt> || <tt>DoRun</tt> || Run the built program with the selected emulator ||
|-
| <tt>'''rebuild'''</tt> || All <tt>DoXxx</tt> || Clean all generated files, then do all steps ||
|-
| <tt>'''define=<name>[:value]'''</tt> || <tt>CompileOpt</tt> || Define a compilation symbol (can be used multiple times) || <tt>define=MYDEF:123</tt>
|-
| <tt>'''help'''</tt> || || Display this command-line arguments list ||
|}

Note: For parameters that take a value, there should be no space before or after the equal sign '<tt>=</tt>'.

=== Example ===

==== Set target ====

The following command allows you to overwrite the build target from the command line.
E.g.: <tt>build DOS2</tt> (MSX-DOS2 application) or <tt>build ROM_48K</tt> (48 KB plain-ROM cartridge).
<syntaxhighlight lang="console">
..\..\tools\build\Node\node.exe ..\..\engine\script\js\build.js target=%1
</syntaxhighlight>

==== Transfert all parameters ====

It is recommended that you pass all command line parameters to the build script.
This allows you to fully configure your build sessions according to your needs.
Here is an example of a build.bat script:
<syntaxhighlight lang="console">
..\..\tools\build\Node\node.exe ..\..\engine\script\js\build.js %1 %2 %3 %4 %5 %6 %7 %8 %9
</syntaxhighlight>

== Misc ==

Previously, the Build tool was written in Windows batch format.
Here is a [[Batch to JS conversion guide|guide to convert the configuration files to use the new Build tool]].

⚠️ Old batch version of the build tool is no longer supported start from MSXgl 1.0.1 version. Please update your project configuration.

AppSignature

2026-04-18T11:21:33Z

Aoineko: /* Creator ID */

This [[Build tool]] option allow to add an '''application signature''' to binary data (right after the header).

The MSXgl signature format is directly inspired by the meta-data used by '''Konami''' to identify their cartridges and add cross-games options.

== Definition ==

Application's signature is 4 bytes long and composed of:
* <tt>AppCompany</tt>: 2 bytes for the creator ID ([[#Creator ID|reserve yours!]]),
* <tt>AppID</tt>: 2 bytes for the product ID (the numbering of the applications is up to each creator).

<syntaxhighlight lang="js">
//-- Add application signature to binary data (boolean)
AppSignature = true;

//-- Application creator ID. Can be 2 character string or 16-bits integer (0~65535)
AppCompany = "GL";

//-- Application product ID. Can be 2 character string or 16-bits integer (0~65535)
AppID = 0;
</syntaxhighlight>

If 2-character string is recommended for creator ID and integer for product ID, in fact, both of those parameters can be any of:
* 2-character string (<tt>"MX"</tt>, <tt>"a7"</tt> for example),
* 16-bits decimal unsigned number (<tt>12345</tt> for example),
* 16-bits hexadecimal number starting with <tt>0x</tt> (<tt>0x0750</tt> for example).

For example, the header first 2 words of Konami's ''Penguin Adventure'' are <tt>"CD", 0x4307</tt>. <tt>"CD"</tt> is one of the signature used by Konami to mark there ROM (see next section) and <tt>0x4307</tt> show in binary viewer the number 0743... the serial number of ''Penguin Adventure'' (RC743).

You can also add extra data using [[AppExtra]] option. {{WIP}}

== Programming ==
If <tt>AppSignature</tt> is set to TRUE in Build tool configuration, then <tt>APPSIGN</tt> is defined in your C program.

Application signature is put just after the binary header:
* At ROM header address +0x0010 (should be 0x4010 or 0x8010),
* At Basic binary header address +0x0007 (should be 0x8007),
* At DOS binary start address +0x0002 (should be 0x0102).

Define an external variable as <tt>g_AppSignature</tt> if you need to access the data from your program.
It can be defined in several ways depending on your needs. For example:
<syntaxhighlight lang="c">
extern const u16 g_AppSignature[2];
</syntaxhighlight><syntaxhighlight lang="c">
extern const u8 g_AppSignature[4];
</syntaxhighlight>
Keep in mind than MSX store data as Less significant byte first (Little endian).

Note: For ROM targets, if a [[ROM type signature]] is present at offset +0010h, then the application signature is placed just after (header +0x0018)

== Creator ID ==
Some creators' ID are already reserved:
{| class="wikitable sortable"
! ID !! Rel !! Creator's name
|-
| <tt>0x00??</tt> || ➖ || ''Reserved''
|-
| <tt>"2N"</tt> || ✔️ || 2NICE
|-
| <tt>"AB"</tt> || ✔️ || Konami (''Boxing'' and ''Football'')
|-
| <tt>"AM"</tt> || ✔️ || Associazione MSX Italia
|-
| <tt>"AG"</tt> || || Antxiko Gorjon
|-
| <tt>"B5"</tt> || ✔️ || Bik5 (J. Bikker)
|-
| <tt>"CC"</tt> || ✔️ || Casper Croes
|-
| <tt>"CD"</tt> || ✔️ || Konami (many games)
|-
| <tt>"CL"</tt> || || Chien Loco
|-
| <tt>"EF"</tt> || ✔️ || Konami (''Pennant Race'' and ''Knightmare 3'')
|-
| <tt>"FD"</tt> || ✔️ || FutureDisk
|-
| <tt>"FP"</tt> || ✔️ || Fausto
|-
| <tt>"JP"</tt> || || Johan de Punder
|-
| <tt>"GH"</tt> || ➖ || ''Reserved''
|-
| <tt>"GL"</tt> || ✔️ || MSXgl (samples)
|-
| <tt>"H_"</tt> || || Peruho
|-
| <tt>"HN"</tt> || || Hando
|-
| <tt>"MO"</tt> || ✔️ || MO5.com
|-
| <tt>"NB"</tt> || ✔️ || Nicola "8bit"
|-
| <tt>"PH"</tt> || ✔️ || Pixel Phenix
|-
| <tt>"PP"</tt> || ✔️ || Pixel Phenix (obsolete)
|-
| <tt>"RC"</tt> || ➖ || ''Reserved''
|-
| <tt>"RG"</tt> || ✔️ || Rutagames (Diogo Patrão)
|-
| <tt>"RO"</tt> || ➖ || ''Reserved for [[ROM type signature]]''
|-
| <tt>"RS"</tt> || ✔️ || RoboSoft
|-
| <tt>"TL"</tt> || || Tele-Line
|-
| <tt>"TT"</tt> || ✔️ || Thomas ‘Totta’ Lundgren
|-
| <tt>"YZ"</tt> || ✔️ || Konami (''Game Master 2)''
|-
| <tt>"WD"</tt> || || Wim Dewijngaert
|-
| <tt>"ZR"</tt> || || Zdrmonster Productions
|-
| <tt>"XX"</tt> || ➖ || ''Reserved''
|-
| <tt>0xFF??</tt> || ➖ || ''Reserved''
|}

Note:
* Come on the MSXgl's [https://discord.gg/pMeadGfv8E Discord Server] to reserve your own creator ID.
* Creator ID are only definitively assigned when an application is published with this code.

== Known signed applications ==
List of released applications that contain compatible signature.

{| class="wikitable sortable"
! C !! App !! Author !! Application
|-
| <tt>"B5"</tt> || <tt>"EM"</tt> || Bik5 (J. Bikker) || ''Eggy's Maze''
|-
| <tt>"B5"</tt> || <tt>"R3"</tt> || Bik5 (J. Bikker) || ''DELTA''
|-
| <tt>"CC"</tt> || <tt>"PC"</tt> || Casper Croes || ''Phenix Corrupta''
|-
| <tt>"CC"</tt> || <tt>"TR"</tt> || Casper Croes || ''Soul Trapped''
|-
| <tt>"FD"</tt> || <tt>"LW"</tt> || FutureDisk || ''A Lone Wolf''
|-
| <tt>"FP"</tt> || <tt>"EX"</tt> || Fausto Pracek || ''Sam.Pr Explore''
|-
| <tt>"FP"</tt> || <tt>"MW"</tt> || Fausto Pracek || ''Martian War''
|-
| <tt>"FP"</tt> || <tt>"SL"</tt> || Fausto Pracek || ''Soccer League''
|-
| <tt>"FP"</tt> || <tt>"SP"</tt> || Fausto Pracek || ''Sam.Pr''
|-
| <tt>"NB"</tt> || <tt>"TC"</tt> || Nicola "8bit" || ''The New Castle''
|-
| <tt>"PP"</tt> || <tt>"CR"</tt> || Pixel Phenix || ''Crawlers (MSXdev'23)''
|-
| <tt>"PH"</tt> || <tt>001</tt> || Pixel Phenix || ''Crawlers (cartridge)''
|-
| <tt>"PH"</tt> || <tt>003</tt> || Pixel Phenix || ''Peng Pong''
|-
| <tt>"RG"</tt> || <tt>"TM"</tt> || Rutagames || ''TerMSX Multi''
|-
| <tt>"RS"</tt> || <tt>"P9"</tt> || RoboSoft || ''Planet X9''
|-
| <tt>"RS"</tt> || <tt>"PE"</tt> || RoboSoft || ''Attack of the Petscii Robots''
|-
| <tt>"TT"</tt> || <tt>"TP"</tt> || Thomas ‘Totta’ Lundgren || ''Tetpuz''
|-
| <tt>"TT"</tt> || <tt>"DL"</tt> || Thomas ‘Totta’ Lundgren || ''Doomlings''
|-
| <tt>"MO"</tt> || <tt>"R5"</tt> || MO5.com || ''Room 5''
|-
| <tt>"GL"</tt> || <tt>?</tt> || MSXgl || (samples)
|-
| <tt>"AB"</tt> || <tt>?</tt> || Konami || (''Boxing'' and ''Football'')
|-
| <tt>"CD"</tt> || <tt>?</tt> || Konami || (many games)
|-
| <tt>"EF"</tt> || <tt>?</tt> || Konami || (''Pennant Race'' and ''Knightmare 3'')
|-
| <tt>"YZ"</tt> || <tt>?</tt> || Konami || (''Game Master 2)''
|}

NEO mapper/Extension

2026-04-13T21:34:17Z

Aoineko: /* 0x05: Activate device */

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

Examples:
{| class="wikitable"
|-
! Action || Pseudo-code
|-
| Activate information in bank 2 of NEO-16 || <tt>[0x7005] = 0xC0</tt>
|-
| Read information (offset +5) from bank 2 of NEO-16 || <tt>BankSize = [0x8005]</tt>
|-
| Disactivate information in bank 2 of NEO-16 || <tt>[0x7005] = 0x80</tt>
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| RAM Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device ID
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcEnableTable[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_Read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcEnableTable[0x04] = SRAM_Enable; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the extended feature.

NEO mapper/Extension

2026-04-13T21:32:59Z

Aoineko:

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

Examples:
{| class="wikitable"
|-
! Action || Pseudo-code
|-
| Activate information in bank 2 of NEO-16 || <tt>[0x7005] = 0xC0</tt>
|-
| Read information (offset +5) from bank 2 of NEO-16 || <tt>BankSize = [0x8005]</tt>
|-
| Disactivate information in bank 2 of NEO-16 || <tt>[0x7005] = 0x80</tt>
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| RAM Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcEnableTable[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_Read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcEnableTable[0x04] = SRAM_Enable; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the extended feature.

NEO mapper/Extension

2026-04-13T21:26:50Z

Aoineko:

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

Examples:
{| class="wikitable"
|-
! Action || Pseudo-code
|-
| Activate information in bank 2 of NEO-16 || <tt>[0x7005] = 0xC0</tt>
|-
| Read information (offset +5) from bank 2 of NEO-16 || <tt>BankSize = [0x8005]</tt>
|-
| Disactivate information in bank 2 of NEO-16 || <tt>[0x7005] = 0x80</tt>
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| RAM Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcEnableTable[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_Read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcEnableTable[0x04] = SRAM_Enable; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the feature.

NEO mapper/Extension

2026-04-13T21:26:10Z

Aoineko: /* Extension example */

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

Examples:
{| class="wikitable"
|-
! Action || Pseudo-code
|-
| Activate information in bank 2 of NEO-16 || <tt>[0x7005] = 0xC0</tt>
|-
| Read information (offset +5) from bank 2 of NEO-16 || <tt>BankSize = [0x8005]</tt>
|-
| Disactivate information in bank 2 of NEO-16 || <tt>[0x7005] = 0x80</tt>
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| RAM Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcEnableTable[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_Read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcTab[0x04] = SRAM_Enable; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the feature.

NEO mapper/Extension

2026-04-13T21:23:56Z

Aoineko: /* Programmable processor and emulation */

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

Examples:
{| class="wikitable"
|-
! Action || Pseudo-code
|-
| Activate information in bank 2 of NEO-16 || <tt>[0x7005] = 0xC0</tt>
|-
| Read information (offset +5) from bank 2 of NEO-16 || <tt>BankSize = [0x8005]</tt>
|-
| Disactivate information in bank 2 of NEO-16 || <tt>[0x7005] = 0x80</tt>
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| RAM Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcEnableTable[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcTab[0x04] = SRAM_Init; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the feature.

NEO mapper/Extension

2026-04-13T21:12:03Z

Aoineko: /* 0x04: Activate SRAM/FRAM */

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

Examples:
{| class="wikitable"
|-
! Action || Pseudo-code
|-
| Activate information in bank 2 of NEO-16 || <tt>[0x7005] = 0xC0</tt>
|-
| Read information (offset +5) from bank 2 of NEO-16 || <tt>BankSize = [0x8005]</tt>
|-
| Disactivate information in bank 2 of NEO-16 || <tt>[0x7005] = 0x80</tt>
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| RAM Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcTab[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcTab[0x04] = SRAM_Init; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the feature.

NEO mapper/Extension

2026-04-13T21:11:51Z

Aoineko: /* 0x00: Cartridge information */

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| ROM Bank
|}

Examples:
{| class="wikitable"
|-
! Action || Pseudo-code
|-
| Activate information in bank 2 of NEO-16 || <tt>[0x7005] = 0xC0</tt>
|-
| Read information (offset +5) from bank 2 of NEO-16 || <tt>BankSize = [0x8005]</tt>
|-
| Disactivate information in bank 2 of NEO-16 || <tt>[0x7005] = 0x80</tt>
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcTab[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcTab[0x04] = SRAM_Init; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the feature.

NEO mapper

2026-04-13T21:05:19Z

Aoineko:

<div style="float:right">[[NEO mapper|EN]] | [[NEO mapper/JA|JA]]</div>
Here's a proposal for a mapper format operating with a 16-bit segment register and allowing ROMs larger than the 2/4 MB limit of classic mappers.

== Specifications ==

=== Principles ===

This mapper format is designed to facilitate the creation of MSX games, not only by increasing the size of the ROM available for content, but also by offering programmers new possibilities for organizing their code and data.

Like conventional mappers, the basic idea is to use data write signals to the cartridge to change mapper registers value and thus, the ROM segment visible in each of the mapper's banks (sub-pages). So, predefined addresses can be used to write to the mapper registers (see [[#Format|tables below]]).
Read accesses, however, work as normal accesses to the memory visible through the banks.

The format is inspired by ASCII8/16 mappers and is even compatible with most ROMs using these formats (the only exception being the rare programs that use odd-numbered addresses to switch banks). The aim of this proximity to these classic mappers is to facilitate the work of manufacturers to create cartridge in this new mapper format.

Compared to conventional mappers, this proposal is based on two new main features:
* A 16-bit segment register,
* Banks covering page #0 of MSX memory space (address 0000h~3FFFh).

Usage of page #0 makes it easy to have an extra 16 KB accessible at any time (either by temporarily disabling interrupts for the duration of accesses, or by adding its own ISR).

For the time being, we propose to reserve the 2 most significant bits of the 16-bit bank registers for future extensions of the format (such as SRAM or sound chips support for example).
This leaves 14 bits to select which segment is visible in each bank, for a maximum of 16384 segments.
The reserved bits, must be set to 0.

{| class="wikitable"
|-
!colspan="8"| Higher byte
|
!colspan="8"| Lower byte
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8
|
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
| 0 || 0
|colspan="6"| Segment MSB
|
|colspan="8"| Segment LSB
|}

The maximum ROM size is therefore 128 MB (for 8 KB segments) or 256 MB (for 16 KB segments).

=== Write Access ===

Write access to the mapper is use to change the value of the bank switching register (where you can select the ROM segment visible through a bank).
Bellow is the list of the predefined segment switching addresses.

As this new mapper uses 16-bit segment switching registers, it uses 2 bytes for the segment number to be selected in each bank.
All even-numbered addresses (bit #0 of the address set to 0) access the low byte of the 16-bit register, while odd-numbered addresses (bit #0 of the address set to 1) access the high byte.
This way, the segment number can be initialized at once with the [[#Bank switching cost|Z80 instructions for 16-bit memory write access]].

==== NEO-8 mapper ====

* Size of a segment: 8 KB
* Segment switching addresses:
{| class="wikitable"
! Bank (8kB) !! Switching address !! Initial segment
|-
| 0: 0000h~1FFFh || 5000h (mirror at 1000h, 9000h and D000h) || 0000h
|-
| 1: 2000h~3FFFh || 5800h (mirror at 1800h, 9800h and D800h) || 0000h
|-
| 2: 4000h~5FFFh || 6000h (mirror at 2000h, A000h and E000h) || 0000h
|-
| 3: 6000h~7FFFh || 6800h (mirror at 2800h, A800h and E800h) || 0000h
|-
| 4: 8000h~9FFFh || 7000h (mirror at 3000h, B000h and F000h) || 0000h
|-
| 5: A000h~BFFFh || 7800h (mirror at 3800h, B800h and F800h) || 0000h
|}
* Maximum number of segments: 16384
* Maximum ROM size: 128 MB

==== NEO-16 mapper ====

* Size of a segment: 16 KB
* Segment switching addresses:
{| class="wikitable"
! Bank (16kB) !! Switching address !! Initial segment
|-
| 0: 0000h~3FFFh || 5000h (mirror at 1000h, 9000h and D000h) || 0000h
|-
| 1: 4000h~7FFFh || 6000h (mirror at 2000h, A000h and E000h) || 0000h
|-
| 2: 8000h~BFFFh || 7000h (mirror at 3000h, B000h and F000h) || 0000h
|}
* Maximum number of segments: 16384
* Maximum ROM size: 256 MB

=== Read Access ===
When mapper is selected, read accesses to memory pages 0, 1 and 2 (addresses 0000h to BFFFh), are redirected to a given ROM segment according to the value of the bank register corresponding to the address.

For page 3, read accesses are invalid and the value returned is undefined and should not be used. Implementations of the NEO mapper should return the value FFh if page 3 is read, but this value is not guaranteed by the mapper specifications.

=== Detection ===
For emulators and flash tool to detect the NEO mappers, the ROM have to include the following 8 bytes signature right after the 16 bytes ROM header:
* "<tt>ROM_NEO8</tt>" for NEO-8 mapper,
* "<tt>ROM_NE16</tt>" for NEO-16 mapper.

The ROM header (starting with "AB") must be in the first ROM segment at offset 0.
The signature is therefore located at offset 16 of the ROM and may be visible to the Z80 on start-up at addresses 0010h, 4010h and 8010h.

Note: Signature characters have been carefully choosed to prevent existing ROMs to generate false positive signature (See [[ROM type signature]]).

== Support ==

=== Hardware ===
Hardware supporting NEO mapper:
* '''[https://www.msxpico.com/ MSX Pico]''' (normal or WiFi): Support for NEO-8 and NEO-16 mappers up to ~15 MB (firmware 1.25 or above).
* '''[https://www.msxpico.com/ MSX Pico+]''': Support for NEO-8 and NEO-16 mappers up to ~14 MB (firmware 2.12 or above).
* '''[https://github.com/cristianoag/msx-picoverse-public PicoVerse] 2040 and 2350''': Support for NEO-8 and NEO-16 mappers up to ~15 MB.
* '''[https://github.com/arkadiuszmakarenko/RISKYMSX RISKY MSX]''': Support for NEO-8 and NEO-16 mappers up to 256 KB.
* '''Mega-USB 512''': ''WIP hardware...''

=== Emulator ===
Emulators supporting NEO mapper:
* {{Emulicious}} '''Emulicious''': Full support for NEO-8 and NEO-16 mappers.
* {{MSXEC}} '''MSXEC''': Support NEO-8 and NEO-16 mappers up to 64 MB (version 20260303 or above).
* {{openMSX}} '''openMSX''': Full support for NEO-8 and NEO-16 mappers (version 20.0 or above).
* {{WebMSX}} '''WebMSX''': Full support for NEO-8 and NEO-16 mappers (version 6.0.7 or above).

=== MSXgl ===

Both NEO-8 and NEO-16 mappers are supported. Use respectively <tt>ROM_NEO8</tt> and <tt>ROM_NEO16</tt> as target format.

MSXgl uses macros to wrap quick bank switching mechanisms. It would therefore be totally transparent for a user to switch, for example, from an ASCII8 or even Konami-SCC mapper, to an NEO-8 mapper.

<syntaxhighlight lang="c">
#define SET_BANK_SEGMENT(bank, segment) /* ... */

// Make segment #30 visible through bank #1
SET_BANK_SEGMENT(1, 30);
</syntaxhighlight>

MSXgl initialize the banks with a unique segment each, to offer the largest possible space available to the user:

<img style="width:400px; margin:0.5em;" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/doc/mapper_neo8.png" />
<img style="width:400px; margin:0.5em;" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/doc/mapper_neo16.png" />

Note: When the application start, segment at 0x4000 always point to segment 0 that include the ROM header. See [[Create a mapped ROM#NEO mapper]] for more details.

== Appendix ==

=== Segment switching address format ===

From a software point of view, the segment switching address is defined as:
{| class="wikitable"
|-
!colspan="17"| 16-bit address
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8
|
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
| P || P || B || B || B || x || x || x || || x || x || x || x || x || x || x || R
|}
Where:
* 'PP' (0-3) is the page selection for the MSX to redirect access to the mappers slot. Those bits are ignored by the mapper and contribute to mirroring, but the mapper registers can only be accessed from selected pages.
* 'BBB' (0-7) is the bank's register to write in. All unspecified values are discarded.
:{| class="wikitable"
! Bank !! NEO-8 !! NEO-16
|-
| 0 || 010 || 010
|-
| 1 || 011 || 100
|-
| 2 || 100 || 110
|-
| 3 || 101 ||
|-
| 4 || 110 ||
|-
| 5 || 111 ||
|}
* 'R' (0-1) is the segment switching register's byte selector (0: less significant byte; 1: most significant byte).
* 'x' can be any value (generating mirroring).

So, mirroring occurs on all addresses from the given switching address +2 to the switching address +7FEh on all even-numbered addresses. For example, 5000h is mirrored at 5002h~57FEh.

=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers for programmable processor based cartridges or for emulators:
{|
|-
| NEO-8 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[6]; // Bank switching register value

// Handle device initialization
void NEO8_Init()
{
for (uint8 i=0; i<6; i++)
bankValue[i] = 0;
}

// Handle write access
void NEO8_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 11) & 0x07) - 2;
if (bank > 5)
return; // skip
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}

// Handle read access
uint8 NEO8_Read(uint16 address)
{
uint8 bank = address >> 13;
if (bank > 5)
return 0xFF; // skip
return romData[(bankValue[bank]) << 13 + (address & 0x1FFF)];
}
</syntaxhighlight>
| NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Handle device initialization
void NEO16_Init()
{
bankValue[0] = bankValue[1] = bankValue[2] = 0;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1;
if (bank > 2)
return; // skip
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14;
if (bank > 2)
return 0xFF; // skip
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>
|}

=== Sample program ===
A sample program is available for testing purpose on: https://aoineko.org/msx/targets/rom/

It is available in various sizes:
* NEO-8: 256 KB to 32 MB
* NEO-16: 256 KB to 64 MB

=== Bank switching cost ===
For a program using NEO mapper, the cost of switching only the lower or higher byte of the 16-bit segment register is the same that switching segment for standard ASCII/Konami mappers.
<syntaxhighlight lang="ini">
; Direct access (22 t-states)
LD A,n ; 8 t-states
LD (nn),A ; 14 t-states

; Indirect access (22 t-states)
LD HL,nn ; 11 t-states
LD (HL),n ; 11 t-states
</syntaxhighlight>

Although a program can avoid having to change the 2 bytes (16-bit) of the segment register at once, there are cases where this may be necessary. In such cases, the cost is higher, but remains reasonable.
<syntaxhighlight lang="ini">
; Direct access (28 t-states)
LD HL,nn ; 11 t-states
LD (nn),HL ; 17 t-states

; Indirect access (40 t-states)
LD HL,nn ; 11 t-states
LD (HL),n ; 11 t-states
INC HL ; 7 t-states
LD (HL),n ; 11 t-states
</syntaxhighlight>

=== Logos ===
Here are the logos you can use to indicate that a product is compatible with the NEO mapper:

[https://aoineko.org/msx/files/neomapper8b-logo.png <img style="width:128px" src="https://aoineko.org/msx/files/neomapper8b-logo.png" />]
[https://aoineko.org/msx/files/neomapper8w-logo.png <img style="width:128px" src="https://aoineko.org/msx/files/neomapper8w-logo.png" />]
[https://aoineko.org/msx/files/neomapper16b-logo.png <img style="width:128px" src="https://aoineko.org/msx/files/neomapper16b-logo.png" />]
[https://aoineko.org/msx/files/neomapper16w-logo.png <img style="width:128px" src="https://aoineko.org/msx/files/neomapper16w-logo.png" />]

== Change log ==
* Version 1.0 (2024/02/12)
** Original version
* Version 1.1 (2024/02/20)
** Changed mappers signature to minimize the risk of an old cartridge generating a false positive and to comply to [[ROM type signature]] format.
** Added clarification on PP and BBB values for bank switching addresses.
** Added clarification for read access to the mapper and especially when try to read the page 3.
* Version 1.2 (2026/04/06)
** Added optional official logo for NEO mapper product.
** Added bits 12 and 13 to the register value, increasing the maximum number of segments from 4096 to 16384.
[[Category:Proposal]][[Category:Proposal/Mapper]]

NEO mapper

2026-04-13T21:04:14Z

Aoineko:

<div style="float:right">[[NEO mapper|EN]] | [[NEO mapper/JA|JA]]</div>
Here's a proposal for a mapper format operating with a 16-bit segment register and allowing ROMs larger than the 2/4 MB limit of classic mappers.

== Specifications ==

=== Principles ===

This mapper format is designed to facilitate the creation of MSX games, not only by increasing the size of the ROM available for content, but also by offering programmers new possibilities for organizing their code and data.

Like conventional mappers, the basic idea is to use data write signals to the cartridge to change mapper registers value and thus, the ROM segment visible in each of the mapper's banks (sub-pages). So, predefined addresses can be used to write to the mapper registers (see [[#Format|tables below]]).
Read accesses, however, work as normal accesses to the memory visible through the banks.

The format is inspired by ASCII8/16 mappers and is even compatible with most ROMs using these formats (the only exception being the rare programs that use odd-numbered addresses to switch banks). The aim of this proximity to these classic mappers is to facilitate the work of manufacturers to create cartridge in this new mapper format.

Compared to conventional mappers, this proposal is based on two new main features:
* A 16-bit segment register,
* Banks covering page #0 of MSX memory space (address 0000h~3FFFh).

Usage of page #0 makes it easy to have an extra 16 KB accessible at any time (either by temporarily disabling interrupts for the duration of accesses, or by adding its own ISR).

For the time being, we propose to reserve the 2 most significant bits of the 16-bit bank registers for future extensions of the format (such as SRAM or sound chips support for example).
This leaves 14 bits to select which segment is visible in each bank, for a maximum of 16384 segments.
The reserved bits, must be set to 0.

{| class="wikitable"
|-
!colspan="8"| Higher byte
|
!colspan="8"| Lower byte
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8
|
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
| 0 || 0
|colspan="6"| Segment MSB
|
|colspan="8"| Segment LSB
|}

The maximum ROM size is therefore 128 MB (for 8 KB segments) or 256 MB (for 16 KB segments).

=== Write Access ===

Write access to the mapper is use to change the value of the bank switching register (where you can select the ROM segment visible through a bank).
Bellow is the list of the predefined segment switching addresses.

As this new mapper uses 16-bit segment switching registers, it uses 2 bytes for the segment number to be selected in each bank.
All even-numbered addresses (bit #0 of the address set to 0) access the low byte of the 16-bit register, while odd-numbered addresses (bit #0 of the address set to 1) access the high byte.
This way, the segment number can be initialized at once with the [[#Bank switching cost|Z80 instructions for 16-bit memory write access]].

==== NEO-8 mapper ====

* Size of a segment: 8 KB
* Segment switching addresses:
{| class="wikitable"
! Bank (8kB) !! Switching address !! Initial segment
|-
| 0: 0000h~1FFFh || 5000h (mirror at 1000h, 9000h and D000h) || 0000h
|-
| 1: 2000h~3FFFh || 5800h (mirror at 1800h, 9800h and D800h) || 0000h
|-
| 2: 4000h~5FFFh || 6000h (mirror at 2000h, A000h and E000h) || 0000h
|-
| 3: 6000h~7FFFh || 6800h (mirror at 2800h, A800h and E800h) || 0000h
|-
| 4: 8000h~9FFFh || 7000h (mirror at 3000h, B000h and F000h) || 0000h
|-
| 5: A000h~BFFFh || 7800h (mirror at 3800h, B800h and F800h) || 0000h
|}
* Maximum number of segments: 16384
* Maximum ROM size: 128 MB

==== NEO-16 mapper ====

* Size of a segment: 16 KB
* Segment switching addresses:
{| class="wikitable"
! Bank (16kB) !! Switching address !! Initial segment
|-
| 0: 0000h~3FFFh || 5000h (mirror at 1000h, 9000h and D000h) || 0000h
|-
| 1: 4000h~7FFFh || 6000h (mirror at 2000h, A000h and E000h) || 0000h
|-
| 2: 8000h~BFFFh || 7000h (mirror at 3000h, B000h and F000h) || 0000h
|}
* Maximum number of segments: 16384
* Maximum ROM size: 256 MB

=== Read Access ===
When mapper is selected, read accesses to memory pages 0, 1 and 2 (addresses 0000h to BFFFh), are redirected to a given ROM segment according to the value of the bank register corresponding to the address.

For page 3, read accesses are invalid and the value returned is undefined and should not be used. Implementations of the NEO mapper should return the value FFh if page 3 is read, but this value is not guaranteed by the mapper specifications.

=== Detection ===
For emulators and flash tool to detect the NEO mappers, the ROM have to include the following 8 bytes signature right after the 16 bytes ROM header:
* "<tt>ROM_NEO8</tt>" for NEO-8 mapper,
* "<tt>ROM_NE16</tt>" for NEO-16 mapper.

The ROM header (starting with "AB") must be in the first ROM segment at offset 0.
The signature is therefore located at offset 16 of the ROM and may be visible to the Z80 on start-up at addresses 0010h, 4010h and 8010h.

Note: Signature characters have been carefully choosed to prevent existing ROMs to generate false positive signature (See [[ROM type signature]]).

== Support ==

=== Hardware ===
Hardware supporting NEO mapper:
* '''[https://www.msxpico.com/ MSX Pico]''' (normal or WiFi): Support for NEO-8 and NEO-16 mappers up to ~15 MB (firmware 1.25 or above).
* '''[https://www.msxpico.com/ MSX Pico+]''': Support for NEO-8 and NEO-16 mappers up to ~14 MB (firmware 2.12 or above).
* '''[https://github.com/cristianoag/msx-picoverse-public PicoVerse] 2040 and 2350''': Support for NEO-8 and NEO-16 mappers up to ~15 MB.
* '''[https://github.com/arkadiuszmakarenko/RISKYMSX RISKY MSX]''': Support for NEO-8 and NEO-16 mappers up to 256 KB.
* '''Mega-USB 512''': ''WIP hardware...''

=== Emulator ===
Emulators supporting NEO mapper:
* {{Emulicious}} '''Emulicious''': Full support for NEO-8 and NEO-16 mappers.
* {{MSXEC}} '''MSXEC''': Support NEO-8 and NEO-16 mappers up to 64 MB (version 20260303 or above).
* {{openMSX}} '''openMSX''': Full support for NEO-8 and NEO-16 mappers (version 20.0 or above).
* {{WebMSX}} '''WebMSX''': Full support for NEO-8 and NEO-16 mappers (version 6.0.7 or above).

=== MSXgl ===

Both NEO-8 and NEO-16 mappers are supported. Use respectively <tt>ROM_NEO8</tt> and <tt>ROM_NEO16</tt> as target format.

MSXgl uses macros to wrap quick bank switching mechanisms. It would therefore be totally transparent for a user to switch, for example, from an ASCII8 or even Konami-SCC mapper, to an NEO-8 mapper.

<syntaxhighlight lang="c">
#define SET_BANK_SEGMENT(bank, segment) /* ... */

// Make segment #30 visible through bank #1
SET_BANK_SEGMENT(1, 30);
</syntaxhighlight>

MSXgl initialize the banks with a unique segment each, to offer the largest possible space available to the user:

<img style="width:400px; margin:0.5em;" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/doc/mapper_neo8.png" />
<img style="width:400px; margin:0.5em;" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/doc/mapper_neo16.png" />

Note: When the application start, segment at 0x4000 always point to segment 0 that include the ROM header. See [[Create a mapped ROM#NEO mapper]] for more details.

== Appendix ==

=== Segment switching address format ===

From a software point of view, the segment switching address is defined as:
{| class="wikitable"
|-
!colspan="17"| 16-bit address
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8
|
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
| P || P || B || B || B || x || x || x || || x || x || x || x || x || x || x || R
|}
Where:
* 'PP' (0-3) is the page selection for the MSX to redirect access to the mappers slot. Those bits are ignored by the mapper and contribute to mirroring, but the mapper registers can only be accessed from selected pages.
* 'BBB' (0-7) is the bank's register to write in. All unspecified values are discarded.
:{| class="wikitable"
! Bank !! NEO-8 !! NEO-16
|-
| 0 || 010 || 010
|-
| 1 || 011 || 100
|-
| 2 || 100 || 110
|-
| 3 || 101 ||
|-
| 4 || 110 ||
|-
| 5 || 111 ||
|}
* 'R' (0-1) is the segment switching register's byte selector (0: less significant byte; 1: most significant byte).
* 'x' can be any value (generating mirroring).

So, mirroring occurs on all addresses from the given switching address +2 to the switching address +7FEh on all even-numbered addresses. For example, 5000h is mirrored at 5002h~57FEh.

=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers for programmable processor based cartridges or for emulators:
{|
|-
| NEO-8 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[6]; // Bank switching register value

// Handle device initialization
void NEO8_Init()
{
for (uint8 i=0; i<6; i++)
bankValue[i] = 0;
}

// Handle write access
void NEO8_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 11) & 0x07) - 2;
if (bank > 5)
return; // skip
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}

// Handle read access
uint8 NEO8_Read(uint16 address)
{
uint8 bank = address >> 13;
if (bank > 5)
return 0xFF; // skip
return romData[(bankValue[bank]) << 13 + (address & 0x1FFF)];
}
</syntaxhighlight>
| NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Handle device initialization
void NEO16_Init()
{
bankValue[0] = bankValue[1] = bankValue[2] = 0;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1;
if (bank > 2)
return; // skip
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14;
if (bank > 2)
return 0xFF; // skip
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>
|}

=== Sample program ===
A sample program is available for testing purpose on: https://aoineko.org/msx/targets/rom/

It is available in various sizes:
* NEO-8: 256 KB to 32 MB
* NEO-16: 256 KB to 64 MB

=== Bank switching cost ===
For a program using NEO mapper, the cost of switching only the lower or higher byte of the 16-bit segment register is the same that switching segment for standard ASCII/Konami mappers.
<syntaxhighlight lang="ini">
; Direct access (22 t-states)
LD A,n ; 8 t-states
LD (nn),A ; 14 t-states

; Indirect access (22 t-states)
LD HL,nn ; 11 t-states
LD (HL),n ; 11 t-states
</syntaxhighlight>

Although a program can avoid having to change the 2 bytes (16-bit) of the segment register at once, there are cases where this may be necessary. In such cases, the cost is higher, but remains reasonable.
<syntaxhighlight lang="ini">
; Direct access (28 t-states)
LD HL,nn ; 11 t-states
LD (nn),HL ; 17 t-states

; Indirect access (40 t-states)
LD HL,nn ; 11 t-states
LD (HL),n ; 11 t-states
INC HL ; 7 t-states
LD (HL),n ; 11 t-states
</syntaxhighlight>

=== Logos ===
Here are the logos you can use to indicate that a product is compatible with the NEO mapper:

[https://aoineko.org/msx/files/neomapper8b-logo.png <img style="width:128px" src="https://aoineko.org/msx/files/neomapper8b-logo.png" />]
[https://aoineko.org/msx/files/neomapper8w-logo.png <img style="width:128px" src="https://aoineko.org/msx/files/neomapper8w-logo.png" />]
[https://aoineko.org/msx/files/neomapper16b-logo.png <img style="width:128px" src="https://aoineko.org/msx/files/neomapper16b-logo.png" />]
[https://aoineko.org/msx/files/neomapper16w-logo.png <img style="width:128px" src="https://aoineko.org/msx/files/neomapper16w-logo.png" />]

== Change log ==
* Version 1.0 (2024/02/12)
** Original version
* Version 1.1 (2024/02/20)
** Changed mappers signature to minimize the risk of an old cartridge generating a false positive and to comply to [[ROM type signature]] format.
** Added clarification on PP and BBB values for bank switching addresses.
** Added clarification for read access to the mapper and especially when try to read the page 3.
* Version 1.2 (2026/04/06)
** Added official logo for NEO mapper product.
** Added bits 12 and 13 to the register value, increasing the maximum number of segments from 4096 to 16384.
[[Category:Proposal]][[Category:Proposal/Mapper]]

NEO mapper/Extension

2026-04-13T20:54:53Z

Aoineko: /* 0x00: Cartridge information */

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

Examples:
{| class="wikitable"
|-
! Action || Pseudo-code
|-
| Activate information in bank 2 of NEO-16 || <tt>[0x7005] = 0xC0</tt>
|-
| Read information (offset +5) from bank 2 of NEO-16 || <tt>BankSize = [0x8005]</tt>
|-
| Disactivate information in bank 2 of NEO-16 || <tt>[0x7005] = 0x80</tt>
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcTab[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcTab[0x04] = SRAM_Init; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the feature.

NEO mapper/Extension

2026-04-13T20:53:53Z

Aoineko: /* 0x00: Cartridge information */

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

Examples:
{| class="wikitable"
|-
! Action || Pseudo-code
|-
| Activate information in bank 2 of NEO-16 || <tt>[0x7005] = 0xC0</tt>
|-
| Read information from bank 2 of NEO-16 || <tt>BankSize = [0x8005]</tt>
|-
| Disactivate information in bank 2 of NEO-16 || <tt>[0x7005] = 0x80</tt>
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcTab[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcTab[0x04] = SRAM_Init; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the feature.

NEO mapper/Extension

2026-04-13T20:22:32Z

Aoineko: /* 0x00: Cartridge information */

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

Examples:
{| class="wikitable"
|-
! Case || Pseudo-code
|-
| Activate information in bank 2 of NEO-16 || <tt>[0x7005] = 0xC0</tt>
|-
| Disactivate information in bank 2 of NEO-16 || <tt>[0x7005] = 0x80</tt>
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcTab[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcTab[0x04] = SRAM_Init; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the feature.

NEO mapper/Extension

2026-04-13T20:21:41Z

Aoineko:

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

Examples:
{| class="wikitable"
|-
! Case ||
|-
| Activate information in bank 2 of NEO-16 || <tt>[0x7005] = 0xC0</tt>
|}
==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcTab[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcTab[0x04] = SRAM_Init; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the feature.

NEO mapper/Extension

2026-04-13T20:18:45Z

Aoineko: /* 0x00: Cartridge information */

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

Examples:
{| class="wikitable"
|-
! Case ||
|-
| Activate information in bank 2 of NEO-16 || <tt>[0x] = 0x02</tt>

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcTab[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcTab[0x04] = SRAM_Init; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the feature.

NEO mapper/Extension

2026-04-06T21:13:09Z

Aoineko:

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcTab[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcTab[0x04] = SRAM_Init; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

Then, you just need to call <tt>SRAM_Init()</tt> from <tt>NEO16_Init()</tt> to register the feature.

NEO mapper/Extension

2026-04-06T21:06:26Z

Aoineko: /* Appendix */

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcTab[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
uint8 bank = param & 0x07; // Get bank number
if (bank > 2)
return; // skip (for NEO-16)

sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = bank;
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcTab[0x04] = SRAM_Init; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

NEO mapper/Extension

2026-04-06T21:03:03Z

Aoineko: /* Programmable processor and emulation */

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcTab[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

=== Extension example ===
Here is a pseudo code in C to handle a SRAM extension for NEO mapper:

NEO-16 mapper:
<syntaxhighlight lang="c">
uint8 sramSeg; // Current SRAM segment [0:15]
uint8 sramBank; // Current bank where SRAM is selected (0xFF if not selected)
uint8* sramData; // SRAM data (hardware specific)

// Write to SRAM
void SRAM_Write(uint16 address, uint8 value)
{
sramData[(sramSeg * 0x2000) + (address & 0x1FFF)] = value; //
}

// Read from SRAM
uint8 SRAM_read(uint16 address)
{
return sramData[(sramSeg * 0x2000) + (address & 0x1FFF)];
}

// Enable/disable SRAM feature
void SRAM_Enable(bool enable, uint8 param)
{
if (sramBank != 0xFF) // Disable previous SRAM registration
{
if (funcWriteTable[sramBank] == SRAM_Write)
funcWriteTable[sramBank] = NULL;
if (funcReadTable[sramBank] == SRAM_Read)
funcReadTable[sramBank] = NULL;
sramBank = 0xFF;
}

if (enable) // Enable a SRAM segment in the given bank
{
sramSeg = (param >> 4) & 0x0F; // SRAM segment number
sramBank = param & 0x07; // Mapper bank (todo: check if bank number is valid)
funcWriteTable[sramBank] = SRAM_Write; // Register SRAM callbacks
funcReadTable[sramBank] = SRAM_Read;
}
}

// Initialize SRAM feature
void SRAM_Init()
{
sramBank = 0xFF;
funcTab[0x04] = SRAM_Init; // Register to function 0x04 (SRAM/FRAM feature)
}
</syntaxhighlight>

NEO mapper/Extension

2026-04-06T20:51:32Z

Aoineko:

{{WARNING|This page is still in the proposal stage and should not yet be considered an official specification.}}

Proposal for an extension to the [[NEO mapper]] format.

== Specifications ==

=== Principles ===

Any write operation to the NEO mapper with data bit 7 set to 1 and address bit 0 set to 1 is considered an access to extended features. In that case, the mapper bank register is not modified.

All other write operations should be considered normal access to the mapper's bank register.

The data contains:
* The number of an extended function in the mapper
* A bit indicating whether the function should be enabled or disabled

The address contains an 8-bit parameter to be passed to the function.
{|
|-
|
{| class="wikitable"
|+ ADDRESS
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#BBB;" colspan="2"| Page
|style="background-color:#BBB;" colspan="3"| Bank
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="8"| Parameter
|style="background-color:#FAA;"| 1
|}
|
{| class="wikitable"
|+ DATA
|-
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
|style="background-color:#FAA;"| 1
|style="background-color:#AAF;"| A
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Function
|}
|}

=== Functions ===
==== 0x00: Cartridge information ====
When activated, any read access to the given bank will return the cartridge information (8 KB, mirrored on NEO-16).
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x01: Cartridge configuration ====

==== 0x04: Activate SRAM/FRAM ====
When activated, any read/write access to the specified bank (defined in the parameter) is redirected to the selected segment of the SRAM/FRAM.

SRAM/FRAM is accessed through 8 KB segments (on the NEO-16, the segment is mirrored).

Up to 16 segments can be accessed, for a total capacity of 128 KB.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#AAF;" colspan="4"| Segment
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Bank
|}

==== 0x05: Activate device ====
Activate or disactivate the given device.
{| class="wikitable"
|+ PARAMETER
|-
! 8 || 7 || 6 || 5 || 4 || 3 || 2 || 1
|-
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#BBB;"| 0
|style="background-color:#AAF;" colspan="5"| Device
|}

Devices:
* <tt>00</tt>: MSX-Music (OPLL)
* <tt>01</tt>: MSX-Audio
* <tt>02</tt>: SCC
* <tt>03</tt>: SCC+
* <tt>04</tt>: 2nd PSG (port 10h)
* <tt>05</tt>: Darky (2 x ePSG)
* <tt>06</tt>: Darky Jr. (2 x PSG)
* <tt>08</tt>: OPM (SFK-01, SFG-01 et SFG-05 ver.1)
* <tt>09</tt>: OPP (SFG-05 ver.2)
* <tt>12</tt>: OPL4
* <tt>15</tt>: SAM2695

== Appendix ==
=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers extension for programmable processor based cartridges or for emulators:

NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Extended function prototypes
typedef void (*funcEnable_t)(bool, uint8);
typedef void (*funcWrite_t)(uint16, uint8);
typedef uint8 (*funcRead_t)(uint16);
// Extended functions table
funcEnable_t funcEnableTable[32];
funcWrite_t funcWriteTable[3];
funcRead_t funcReadTable[3];

// Handle device initialization
void NEO16_Init()
{
for (uint8 i = 0; i < 3; i++)
{
bankValue[i] = 0x0000;
funcWriteTable[i] = NULL;
funcReadTable[i] = NULL;
}
for (uint8 i = 0; i < 32; i++)
funcTab[i] = NULL;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1; // Get the corresponding bank number
if (bank > 2)
return; // skip

if (funcWriteTable[bank] != NULL) // Check for bank write callback
{
funcWriteTable[bank](address, value);
}
else if ((address & 0x0001) && (value & 0x80)) // Handle extended function
{
uint8 funcId = value & 0x3F; // Get function ID
if (funcEnableTable[funcId] != NULL)
funcEnableTable[funcId](value & 0x40, (address >> 1) & 0xFF); // Execute function specific code
}
else // Write to the given bank register
{
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14; // Get the corresponding bank number
if (bank > 2)
return 0xFF; // skip

if (funcReadTable[bank] != NULL) // Check for bank read callback
return funcReadTable[bank](address);
else
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>

NEO mapper

2026-04-06T20:04:30Z

Aoineko: +2 bits for segment number

<div style="float:right">[[NEO mapper|EN]] | [[NEO mapper/JA|JA]]</div>
Here's a proposal for a mapper format operating with a 16-bit segment register and allowing ROMs larger than the 2/4 MB limit of classic mappers.

== Specifications ==

=== Principles ===

This mapper format is designed to facilitate the creation of MSX games, not only by increasing the size of the ROM available for content, but also by offering programmers new possibilities for organizing their code and data.

Like conventional mappers, the basic idea is to use data write signals to the cartridge to change mapper registers value and thus, the ROM segment visible in each of the mapper's banks (sub-pages). So, predefined addresses can be used to write to the mapper registers (see [[#Format|tables below]]).
Read accesses, however, work as normal accesses to the memory visible through the banks.

The format is inspired by ASCII8/16 mappers and is even compatible with most ROMs using these formats (the only exception being the rare programs that use odd-numbered addresses to switch banks). The aim of this proximity to these classic mappers is to facilitate the work of manufacturers to create cartridge in this new mapper format.

Compared to conventional mappers, this proposal is based on two new main features:
* A 16-bit segment register,
* Banks covering page #0 of MSX memory space (address 0000h~3FFFh).

Usage of page #0 makes it easy to have an extra 16 KB accessible at any time (either by temporarily disabling interrupts for the duration of accesses, or by adding its own ISR).

For the time being, we propose to reserve the 2 most significant bits of the 16-bit bank registers for future extensions of the format (such as SRAM or sound chips support for example).
This leaves 14 bits to select which segment is visible in each bank, for a maximum of 16384 segments.
The reserved bits, must be set to 0.

{| class="wikitable"
|-
!colspan="8"| Higher byte
|
!colspan="8"| Lower byte
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8
|
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
| 0 || 0
|colspan="6"| Segment MSB
|
|colspan="8"| Segment LSB
|}

The maximum ROM size is therefore 128 MB (for 8 KB segments) or 256 MB (for 16 KB segments).

=== Write Access ===

Write access to the mapper is use to change the value of the bank switching register (where you can select the ROM segment visible through a bank).
Bellow is the list of the predefined segment switching addresses.

As this new mapper uses 16-bit segment switching registers, it uses 2 bytes for the segment number to be selected in each bank.
All even-numbered addresses (bit #0 of the address set to 0) access the low byte of the 16-bit register, while odd-numbered addresses (bit #0 of the address set to 1) access the high byte.
This way, the segment number can be initialized at once with the [[#Bank switching cost|Z80 instructions for 16-bit memory write access]].

==== NEO-8 mapper ====

* Size of a segment: 8 KB
* Segment switching addresses:
{| class="wikitable"
! Bank (8kB) !! Switching address !! Initial segment
|-
| 0: 0000h~1FFFh || 5000h (mirror at 1000h, 9000h and D000h) || 0000h
|-
| 1: 2000h~3FFFh || 5800h (mirror at 1800h, 9800h and D800h) || 0000h
|-
| 2: 4000h~5FFFh || 6000h (mirror at 2000h, A000h and E000h) || 0000h
|-
| 3: 6000h~7FFFh || 6800h (mirror at 2800h, A800h and E800h) || 0000h
|-
| 4: 8000h~9FFFh || 7000h (mirror at 3000h, B000h and F000h) || 0000h
|-
| 5: A000h~BFFFh || 7800h (mirror at 3800h, B800h and F800h) || 0000h
|}
* Maximum number of segments: 16384
* Maximum ROM size: 128 MB

==== NEO-16 mapper ====

* Size of a segment: 16 KB
* Segment switching addresses:
{| class="wikitable"
! Bank (16kB) !! Switching address !! Initial segment
|-
| 0: 0000h~3FFFh || 5000h (mirror at 1000h, 9000h and D000h) || 0000h
|-
| 1: 4000h~7FFFh || 6000h (mirror at 2000h, A000h and E000h) || 0000h
|-
| 2: 8000h~BFFFh || 7000h (mirror at 3000h, B000h and F000h) || 0000h
|}
* Maximum number of segments: 16384
* Maximum ROM size: 256 MB

=== Read Access ===
When mapper is selected, read accesses to memory pages 0, 1 and 2 (addresses 0000h to BFFFh), are redirected to a given ROM segment according to the value of the bank register corresponding to the address.

For page 3, read accesses are invalid and the value returned is undefined and should not be used. Implementations of the NEO mapper should return the value FFh if page 3 is read, but this value is not guaranteed by the mapper specifications.

=== Detection ===
For emulators and flash tool to detect the NEO mappers, the ROM have to include the following 8 bytes signature right after the 16 bytes ROM header:
* "<tt>ROM_NEO8</tt>" for NEO-8 mapper,
* "<tt>ROM_NE16</tt>" for NEO-16 mapper.

The ROM header (starting with "AB") must be in the first ROM segment at offset 0.
The signature is therefore located at offset 16 of the ROM and may be visible to the Z80 on start-up at addresses 0010h, 4010h and 8010h.

Note: Signature characters have been carefully choosed to prevent existing ROMs to generate false positive signature (See [[ROM type signature]]).

== Support ==

=== Hardware ===
Hardware supporting NEO mapper:
* '''[https://www.msxpico.com/ MSX Pico]''' (normal or WiFi): Support for NEO-8 and NEO-16 mappers up to ~15 MB (firmware 1.25 or above).
* '''[https://www.msxpico.com/ MSX Pico+]''': Support for NEO-8 and NEO-16 mappers up to ~14 MB (firmware 2.12 or above).
* '''[https://github.com/cristianoag/msx-picoverse-public PicoVerse] 2040 and 2350''': Support for NEO-8 and NEO-16 mappers up to ~15 MB.
* '''[https://github.com/arkadiuszmakarenko/RISKYMSX RISKY MSX]''': Support for NEO-8 and NEO-16 mappers up to 256 KB.
* '''Mega-USB 512''': ''WIP hardware...''

=== Emulator ===
Emulators supporting NEO mapper:
* {{Emulicious}} '''Emulicious''': Full support for NEO-8 and NEO-16 mappers.
* {{MSXEC}} '''MSXEC''': Support NEO-8 and NEO-16 mappers up to 64 MB (version 20260303 or above).
* {{openMSX}} '''openMSX''': Full support for NEO-8 and NEO-16 mappers (version 20.0 or above).
* {{WebMSX}} '''WebMSX''': Full support for NEO-8 and NEO-16 mappers (version 6.0.7 or above).

=== MSXgl ===

Both NEO-8 and NEO-16 mappers are supported. Use respectively <tt>ROM_NEO8</tt> and <tt>ROM_NEO16</tt> as target format.

MSXgl uses macros to wrap quick bank switching mechanisms. It would therefore be totally transparent for a user to switch, for example, from an ASCII8 or even Konami-SCC mapper, to an NEO-8 mapper.

<syntaxhighlight lang="c">
#define SET_BANK_SEGMENT(bank, segment) /* ... */

// Make segment #30 visible through bank #1
SET_BANK_SEGMENT(1, 30);
</syntaxhighlight>

MSXgl initialize the banks with a unique segment each, to offer the largest possible space available to the user:

<img style="width:400px; margin:0.5em;" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/doc/mapper_neo8.png" />
<img style="width:400px; margin:0.5em;" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/doc/mapper_neo16.png" />

Note: When the application start, segment at 0x4000 always point to segment 0 that include the ROM header. See [[Create a mapped ROM#NEO mapper]] for more details.

== Appendix ==

=== Segment switching address format ===

From a software point of view, the segment switching address is defined as:
{| class="wikitable"
|-
!colspan="17"| 16-bit address
|-
! 15 || 14 || 13 || 12 || 11 || 10 || 9 || 8
|
! 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
| P || P || B || B || B || x || x || x || || x || x || x || x || x || x || x || R
|}
Where:
* 'PP' (0-3) is the page selection for the MSX to redirect access to the mappers slot. Those bits are ignored by the mapper and contribute to mirroring, but the mapper registers can only be accessed from selected pages.
* 'BBB' (0-7) is the bank's register to write in. All unspecified values are discarded.
:{| class="wikitable"
! Bank !! NEO-8 !! NEO-16
|-
| 0 || 010 || 010
|-
| 1 || 011 || 100
|-
| 2 || 100 || 110
|-
| 3 || 101 ||
|-
| 4 || 110 ||
|-
| 5 || 111 ||
|}
* 'R' (0-1) is the segment switching register's byte selector (0: less significant byte; 1: most significant byte).
* 'x' can be any value (generating mirroring).

So, mirroring occurs on all addresses from the given switching address +2 to the switching address +7FEh on all even-numbered addresses. For example, 5000h is mirrored at 5002h~57FEh.

=== Programmable processor and emulation ===
Here is a pseudo code in C to handle NEO mappers for programmable processor based cartridges or for emulators:
{|
|-
| NEO-8 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[6]; // Bank switching register value

// Handle device initialization
void NEO8_Init()
{
for (uint8 i=0; i<6; i++)
bankValue[i] = 0;
}

// Handle write access
void NEO8_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 11) & 0x07) - 2;
if (bank > 5)
return; // skip
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}

// Handle read access
uint8 NEO8_Read(uint16 address)
{
uint8 bank = address >> 13;
if (bank > 5)
return 0xFF; // skip
return romData[(bankValue[bank]) << 13 + (address & 0x1FFF)];
}
</syntaxhighlight>
| NEO-16 mapper:
<syntaxhighlight lang="c">
const uint8* romData; // ROM data
uint16 bankValue[3]; // Bank switching register value

// Handle device initialization
void NEO16_Init()
{
bankValue[0] = bankValue[1] = bankValue[2] = 0;
}

// Handle write access
void NEO16_Write(uint16 address, uint8 value)
{
uint8 bank = ((address >> 12) & 0x03) - 1;
if (bank > 2)
return; // skip
if (address & 1) // Set bank register MSB
bankValue[bank] = ((value & 0x0F) << 8) | (bankValue[bank] & 0x00FF);
else // Set bank register LSB
bankValue[bank] = (bankValue[bank] & 0xFF00) | (value);
}

// Handle read access
uint8 NEO16_Read(uint16 address)
{
uint8 bank = address >> 14;
if (bank > 2)
return 0xFF; // skip
return romData[(bankValue[bank]) << 14 + (address & 0x3FFF)];
}
</syntaxhighlight>
|}

=== Sample program ===
A sample program is available for testing purpose on: https://aoineko.org/msx/targets/rom/

It is available in various sizes:
* NEO-8: 256 KB to 32 MB
* NEO-16: 256 KB to 64 MB

=== Bank switching cost ===
For a program using NEO mapper, the cost of switching only the lower or higher byte of the 16-bit segment register is the same that switching segment for standard ASCII/Konami mappers.
<syntaxhighlight lang="ini">
; Direct access (22 t-states)
LD A,n ; 8 t-states
LD (nn),A ; 14 t-states

; Indirect access (22 t-states)
LD HL,nn ; 11 t-states
LD (HL),n ; 11 t-states
</syntaxhighlight>

Although a program can avoid having to change the 2 bytes (16-bit) of the segment register at once, there are cases where this may be necessary. In such cases, the cost is higher, but remains reasonable.
<syntaxhighlight lang="ini">
; Direct access (28 t-states)
LD HL,nn ; 11 t-states
LD (nn),HL ; 17 t-states

; Indirect access (40 t-states)
LD HL,nn ; 11 t-states
LD (HL),n ; 11 t-states
INC HL ; 7 t-states
LD (HL),n ; 11 t-states
</syntaxhighlight>

=== Logos ===
Here are the logos you can use to indicate that a product is compatible with the NEO mapper:

[https://aoineko.org/msx/files/neomapper8b-logo.png <img style="width:128px" src="https://aoineko.org/msx/files/neomapper8b-logo.png" />]
[https://aoineko.org/msx/files/neomapper8w-logo.png <img style="width:128px" src="https://aoineko.org/msx/files/neomapper8w-logo.png" />]
[https://aoineko.org/msx/files/neomapper16b-logo.png <img style="width:128px" src="https://aoineko.org/msx/files/neomapper16b-logo.png" />]
[https://aoineko.org/msx/files/neomapper16w-logo.png <img style="width:128px" src="https://aoineko.org/msx/files/neomapper16w-logo.png" />]

== Change log ==
* Version 1.0 (2024/02/12)
** Original version
* Version 1.1 (2024/02/20)
** Changed mappers signature to minimize the risk of an old cartridge generating a false positive and to comply to [[ROM type signature]] format.
** Added clarification on PP and BBB values for bank switching addresses.
** Added clarification for read access to the mapper and especially when try to read the page 3.
* Version 1.2 (2026/04/06)
** Add bits 12 and 13 to the register value, increasing the maximum number of segments from 4096 to 16384
[[Category:Proposal]][[Category:Proposal/Mapper]]

NEO mapper/Extension

2026-04-06T19:48:55Z

Aoineko:

NEO mapper/Extension

2026-04-06T19:48:30Z

Aoineko:

NEO mapper/Extension

2026-04-06T19:47:24Z

Aoineko: