<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.

<u>Note</u>: 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.
* '''[https://github.com/piigaa-densetu-two-dai/MSXpi MSXπ]''': Support for NEO-16 mappers up to 16 MB.
* '''[https://github.com/piigaa-densetu-two-dai/MSXpi_plus_v2 MSXπ Plus (V2)]''': Support for NEO-16 mappers up to 16 MB.

=== Emulator ===
Emulators supporting NEO mapper:
* {{blueMSX}} '''blueMSX+''': Full support for NEO-8 and NEO-16 mappers.
* {{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|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" />

<u>Note</u>: 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">
extern 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">
extern 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/Extension2

2026-09-26T20:13:07Z

Aoineko: /* Principles */

NEO mapper/Extension2

2026-09-26T20:11:04Z

Aoineko:

2026-09-22T18:32:30Z

Aoineko:

Here is a technique to remove 100% of the C language overhead on calling some of the [https://www.msx.org/wiki/Main-ROM_BIOS BIOS routines].

The idea is to "cast" an address with the signature of a C function so that the calling code initializes the registers properly before calling the BIOS function.

For example, the function <tt>GTSTCK</tt> (<tt>00D5h</tt>) which returns the status of the joystick, takes its input parameter in A and returns its final value in A. Among the possible function signatures, <tt>(u8(*)(u8))</tt> uses these same registers.

Thus, with this function definition...
inline u8 Bios_GetJoystickDirection(u8 port) { return ((u8(*)(u8))R_GTSTCK)(port); }
...the calling code will put the port number into register A, call the <tt>GTSTCK</tt> function, then read the result into register A.

Since the function is inline, we gain C typing verification, while having zero C overhead.

Obviously, this only works with BIOS routines that use registers for which there is a C function signature. There are few of them, but by playing with the <tt>sdcccall1</tt> and <tt>z88dk_fastcall</tt> calling conventions, we still have some possibilities. In the case of a <tt>z88dk_fastcall</tt> signature you have to use a <tt>typedef</tt> to define the signature before you can use it.

Here is a summary of all possible the combinations:

{| class="wikitable"
|-
! !!__sdcccall(0) !!__sdcccall(1) !!__z88dk_fastcall
|-
|colspan="4"|RETURN
|-
|8 bits ||L ||A ||L
|-
|16 bits ||HL ||DE ||HL
|-
|32 bits ||DE-HL ||HL-DE ||DE-HL
|-
|colspan="4"|PARAMETERS
|-
|8 bits ||Stack ||A ||L
|-
|16 bits ||Stack ||HL ||HL
|-
|32 bits ||Stack ||HL-DE ||DE-HL
|-
|8 + 8 bits ||Stack ||A + L ||''Invalid''
|-
|8 + 16 bits ||Stack ||A + DE ||''Invalid''
|-
|16 + 16 bits ||Stack ||HL + DE ||''Invalid''
|-
|16 + 8 bits ||Stack ||HL + Stack ||''Invalid''
|}

You can found many examples in <tt>engine\src\bios.h</tt>.

Free call to BIOS routine

2026-09-22T18:32:15Z

Aoineko:

Here is a technique to remove 100% of the C language overhead on calling some of the [https://www.msx.org/wiki/Main-ROM_BIOS BIOS routines].

The idea is to "cast" an address with the signature of a C function so that the calling code initializes the registers properly before calling the BIOS function.

For example, the function <tt>GTSTCK</tt> (<tt>00D5h</tt>) which returns the status of the joystick, takes its input parameter in A and returns its final value in A. Among the possible function signatures, <tt>(u8(*)(u8))</tt> uses these same registers.

Thus, with this function definition...
inline u8 Bios_GetJoystickDirection(u8 port) { return ((u8(*)(u8))R_GTSTCK)(port); }
...the calling code will put the port number into register A, call the <tt>GTSTCK</tt> function, then read the result into register A.

Since the function is inline, we gain C typing verification, while having zero C overhead.

Obviously, this only works with BIOS routines that use registers for which there is a C function signature. There are few of them, but by playing with the <tt>sdcccall1</tt> and <tt>z88dk_fastcall</tt> calling conventions, we still have some possibilities. In the case of a <tt>z88dk_fastcall</tt> signature you have to use a <tt>typedef</tt> to define the signature before you can use it.

Here is a summary of all possible the combinations:

{| class="wikitable"
|-
! !!__sdcccall(0) !!__sdcccall(1) !!__z88dk_fastcall
|-
|colspan="4"|RETURN
|-
|8 bits ||L ||A ||L
|-
|16 bits ||HL ||DE ||HL
|-
|32 bits ||DE-HL ||HL-DE ||DE-HL
|-
|colspan="4"|PARAMETERS
|-
|8 bits ||Stack ||A ||L
|-
|16 bits ||Stack ||HL ||HL
|-
|32 bits ||Stack ||HL-DE ||DE-HL
|-
|8 + 8 bits ||Stack ||A + L ||Invalid
|-
|8 + 16 bits ||Stack ||A + DE ||Invalid
|-
|16 + 16 bits ||Stack ||HL + DE ||Invalid
|-
|16 + 8 bits ||Stack ||HL + Stack ||Invalid
|}

You can found many examples in <tt>engine\src\bios.h</tt>.

Free call to BIOS routine

2026-09-22T18:31:07Z

Aoineko:

Here is a technique to remove 100% of the C language overhead on calling some of the [https://www.msx.org/wiki/Main-ROM_BIOS BIOS routines].

The idea is to "cast" an address with the signature of a C function so that the calling code initializes the registers properly before calling the BIOS function.

For example, the function <tt>GTSTCK</tt> (<tt>00D5h</tt>) which returns the status of the joystick, takes its input parameter in A and returns its final value in A. Among the possible function signatures, <tt>(u8(*)(u8))</tt> uses these same registers.

Thus, with this function definition...
inline u8 Bios_GetJoystickDirection(u8 port) { return ((u8(*)(u8))R_GTSTCK)(port); }
...the calling code will put the port number into register A, call the <tt>GTSTCK</tt> function, then read the result into register A.

Since the function is inline, we gain C typing verification, while having zero C overhead.

Obviously, this only works with BIOS routines that use registers for which there is a C function signature. There are few of them, but by playing with the <tt>sdcccall1</tt> and <tt>z88dk_fastcall</tt> calling conventions, we still have some possibilities. In the case of a <tt>z88dk_fastcall</tt> signature you have to use a <tt>typedef</tt> to define the signature before you can use it.

Here is a summary of all possible the combinations:

{| class="wikitable'
|-
! !!__sdcccall(0) !!__sdcccall(1) !!__z88dk_fastcall
|-
|spancol="4"|RETURN
|-
|8 bits ||L ||A ||L
|-
|16 bits ||HL ||DE ||HL
|-
|32 bits ||DE-HL ||HL-DE ||DE-HL
|-
|spancol="4"|PARAMETERS
|-
|8 bits Stack ||A ||L
|-
|16 bits ||Stack ||HL ||HL
|-
|32 bits ||Stack ||HL-DE ||DE-HL
|-
|8 + 8 bits ||Stack ||A + L ||Invalid
|-
|8 + 16 bits ||Stack ||A + DE ||Invalid
|-
|16 + 16 bits ||Stack ||HL + DE ||Invalid
|-
|16 + 8 bits ||Stack ||HL + Stack ||Invalid
|}

You can found many examples in <tt>engine\src\bios.h</tt>.