Build tool/BIOSReleaseEvent

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

void BIOS_OnRelease();

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 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 (LibModules) 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 msx-music module first in the list ensures that it appears at the beginning of the ROM.