Build tool/InstallRAMISR

Build tool option InstallRAMISR is used mainly to automatically select RAM in page 0 then copy data there at startup, so ROM cartridge can take advantage of (almost) 16 KB of additional RAM.

This option requires MSX to have at least 64 KB of RAM (otherwise, no RAM will be available on page 0). So only some MSX1 may be compatible but all the MSX2, MSX2+ and MSX turbo R are.

As page 0 (addresses 0x0000-0x3FFF) is the place where MSX will search for interruption handler (ISR), the build tool will automatically copy the selected ISR (see CustomISR option).

InstallRAMISR can also be used to install ISR in page 3 and activate Interrupt mode 2 (IM2) so the system will no longer access to page 0 during interrupt and user can switch page 0 content freely.

InstallRAMISR can take those values:

• "RAMISR_NONE": Don't switch page 0 to RAM
• "RAMISR_PAGE0": Switch page 0 to RAM then install ISR at 0x0038 (mandatory address)
• "RAMISR_SEGMENT0": Switch page 0 to RAM, install ISR at 0x0038 , then copy segment data at 0x0100 (for mapped-ROM)
• "RAMISR_PAGE3": Install ISR in RAM in page 3 and use interrupt mode 2 (IM2)

Note: In the past, this option was a Boolean. We recommend changing its value to one of the above strings, but note that if you keep a Boolean value, the 'true' will be interpreted as "RAMISR_PAGE0" and the 'false' as "RAMISR_NONE".

RAMISR_PAGE0

When using RAMISR_PAGE0 option, you have additional RAM of be used from 0x0100 to 0x3FFF. You can use SDCC's __at() directive to place variables in the memory space.

RAMISR_SEGMENT0

When using RAMISR_SEGMENT0 option, you have to define a source code file named {projectName}_p0.c (or .asm or .s to add assembler source) and it will be automatically added to your mapper data and copy at statup in page 0. Code and data from your _p0 file will be available starting from address 0x0100 (after the ISR) so you have a little less than 16 KB available in page 0 (16 KB - 0x100 = 16128 bytes).

The 16 KB content of _p0 will be place in segment after the 32 KB of your main program. Segment number depend of the mapper format your are using:

Mapper	Segments
ASCII-8	#4 and #5
ASCII-16	#2
KONAMI K4	#4 and #5
KONAMI K5 (SCC)	#4 and #5
NEO-8	#6 and #7
NEO-16	#3
YAMANOOTO	#4 and #5
ASCII16-X	#2

When you use this option, these segments are reserved for code and data to be copied on page 0 and cannot be used for anything else.

s_swsprt sample (software sprite) showcase the use of this option.

RAMISR_PAGE3

When using RAMISR_PAGE3 option, the boot sequence install the interrupt handler in RAM, setup a vector table and activate Interrupt mode 2 (IM2) so that, when an interrupt occurs, only page 3 will be accessed.

As page 0 is not used anymore by the system, the user can freely use it to have:

• A fixed chunk of 16 KB of ROM (for 48 KB plain-ROM),
• Freely switchable segments using NEO mapper:
  • NEO-16: 1 bank of 16 KB (0x0000h~0x3FFF),
  • NEO-8: 2 banks of 8 KB (0x0000~0x1FFF and 0x2000~0x3FFF).
• 16 KB of RAM (for MSX with at least 64 KB of RAM).
  • For MSX computers equipped with a Memory mapper, you can freely change the segment displayed on page 0.

This option can only be used with ForceRamAddr=0xC000 (or the default ForceRamAddr=0 as it is equivalent). In this case, C variables will be accumulated starting from address 0xC1C4. Thus, 452 bytes are used for the vector tables (257 bytes) and the ISR code itself.

Note: As IM2 mode use Z80 register I to know where to jump when an interrupt occurs, programmers that would like to use RAMISR_PAGE3 option must not use inline assembler code that use this register.

s_gm3 sample (GM3 mode) showcase the use of this option.