The CPU contains a 4 KiB internal mask ROM holding the BIOS, which is mapped to the address range $0000-$1000. The PM’s BIOS is the exact same ROM on every region’s console.
Although the BIOS is not writable and the first $1000 bytes of the cartridge ROM are ignored, emulators have the capability to run a custom BIOS ROM. Pokemini ships with freebios and NewBIOS is also available. This document will focus on the official BIOS, but all versions should be functionally compatible, but addresses for some functions may be different!
For the full list of IRQs, see its main page
The table is a list of 2-byte absolute addresses into other parts of the BIOS. Because it’s 2-byte, every _int(0xkk)/INT [kkh] instruction will be an even number. In previous documentation (and in PMAS) we instead used the index into the table instead of the address.
Interrupts $00 through $3E (inclusive) are for IRQs generated by the system. Interrupts $40 through $98 (inclusive) are software interrupts available for software to use via _int in C or INT in ASM. Calling interrupt $96 or anything strictly after $98 will cause undefined behavior.
As mentioned, IRQs go first through the BIOS then jump into software. The cookie-cutter template for most of these middlemen is:
PUSH EP ; backup the registers we change
PUSH BR
LD EP, #00h ; paging register for [BR:ll] access
LD BR, #20h ; set BR to access hardware registers
BIT [BR:01h], #20h ; if cart interrupts are not enabled,
CARS Z, loc_0x0257 ; do something (unsure)
POP BR ; restore backup registers before
POP EP ; going into software
JRL 21xxh ; jump to software IRQ handler
Some IRQs are unhandled and end up resetting the console without going into software (before resetting). Two IRQs have special handling related to sleeping the console: cart eject ($26) and power button ($2A), though the latter makes it to software.
For the full list of hardware interrupts, see here
Although they’re all interrupts, we make a distinction between hardware interrupts and software interrupts. Hardware interrupts are interrupts triggered in response to requests from the hardware (IRQs) whereas software interrupts are only triggered from software via the INT operation.
The INT operation can also invoke hardware interrupts, ignoring the interrupt flag’s setting. Since there’s no need to ever do this, they’re on their own page which can also talk about the hardware connectivity. Conversely, software interrupts are the correct way to execute BIOS-level procedures, which we discuss below.
INT [kk] |
Addr | Description |
|---|---|---|
| 40h | $FFF1 | Software-defined interrupt |
| 42h | $0713 | Suspend system |
| 44h | $077C | Sleep |
| 46h | $078B | Sleep with display on |
| 48h | $079D | Shutdown system |
| 4Ah | $07B1 | same as 44h |
| 4Ch | $07E9 | Set startup LCD contrast |
| 4Eh | $0802 | Step & apply startup contrast |
| 50h | $081B | Apply startup LCD contrast |
| 52h | $0821 | Get startup contrast |
| 54h | $0830 | Set temporary LCD contrast |
| 56h | $084E | Turn LCD on |
| 58h | $0871 | Reset LCD |
| 5Ah | $08CB | Turn LCD off |
| 5Ch | $08EC | |
| 5Eh | $0904 | |
| 60h | $0923 | Disable cart eject IRQ+ |
| 62h | $092E | Enable cart eject IRQ+ |
| 64h | $0949 | Disable cart eject IRQ++ |
| 66h | $0961 | Enable cart eject IRQ++ |
| 68h | $097D | Flash cart: turn on and prepare selected game |
| 6Ah | $09E4 | Flash cart: turn on and prepare autoboot game |
| 6Ch | $0A4F | Enable cart eject IRQ and set priority |
| 6Eh | $0A76 | Disable cart eject IRQ |
| 70h | $0A81 | Check cart eject fired, weirdly |
| 72h | $0AA6 | Clock CPU with OSC3 (normal operation) |
| 74h | $0ACD | Clock CPU with OSC1 (low power mode) |
| 76h | $0AE6 | Power off cart slot |
| 78h | $0AF9 | Power on cart slot |
| 7Ah | $0B20 | Check cart is inserted |
| 7Ch | $0B2E | Execute test case ?? |
| 7Eh | $0B8F | Set frame rate divider |
| 80h | $0BA3 | Get frame rate divider |
| 82h | $0BB1 | Test $2001 bits 2~0 are a game struct ID |
| 84h | $047A | Flash cart: read product IDs |
| 86h | $0493 | Flash cart: reset |
| 88h | $04A4 | Flash cart: program byte |
| 8Ah | $04C8 | Flash cart: erase sector |
| 8Ch | $04F5 | Flash cart: enter bank select mode |
| 8Eh | $0506 | Flash cart: select bank |
| 90h | $0517 | Flash cart: allow remapping page 0 |
| 92h | $0529 | Flash cart: remap for reading product IDs |
| 94h | $053A | Select game by game struct ID |
| 96h | $0000 | (not an interrupt) |
| 98h | $0BBD | IR pulse |
TODO: Checks for official use is currently superficial, just whether or not the specific INT operation exists. Each should be tested to see if it’s actually used, and to describe when and why. Some uses are just part of MINLIB and not actually code that’s reached. When discovered, those can be removed from here.
You can define a routine at $00FFF1 which you can call from anywhere via INT [40h] without needing to change NB.
No official software uses this.
Called via INT [42h]
This version backs up the state of the LCD controller, IRQ enable status, IRQ priority and polarity for keypad, enables power key for waking, disables all other IRQs, then halts the system.
When resuming from this state, it will restore everything it backed up and turn the LCD on itself. However, the contents of BA are lost.
This is the safest/easiest form of resuming the game where you left off when the console is powered back on.
Official software which uses this:
Called via INT [44h] (official usage) or INT [4Ah] (no one uses this).
Halts the CPU and LCD without any of the other overhead. It sets the interrupt flags to IRQ2+ so any IRQs you leave enabled without setting their priority to 1 will be able to wake the console, potentially crashing the console if you haven’t configured these properly. See here for more details.
Official software which uses this:
Called via INT [46h]
Similar to 44h but turns off frame copy while leaving the display on. This allows you to freeze the screen to some message while the device is halted.
No official software uses this.
Called via INT [48h]
Powers down the system as much as possible (but still allowing the RTC to keep time) and halts it. When the power button is pressed next, the system will restart (soft reset).
All official software uses this:
Called via:
LD A, #(new startup contrast)
INT [4Ch]
; contents of B lost
This sets the startup contrast then applies it. A can be 0~63 (inclusive) where 0 is fully white and 63 is fully black. The startup contrast set by the bios is 31 (50%). The LCD panel itself normally defaults to 32.
When accessing LCD commands like this, it’s a good idea to disable interrupts (other than ones leading to a system shutdown).
Official software which uses this:
Called via:
; To decrement
OR SC, #1
INT [4Eh]
; contents of B lost
OR A, A
JRS Z, success
; To increment
XOR A, A
INT [4Eh]
; contents of B lost
OR A, A
JRS Z, success
This decrements or increments the startup contrast by 1 then applies it.
When accessing LCD commands like this, it’s a good idea to disable interrupts (other than ones leading to a system shutdown).
While official software (such as Shock Tetris) do step the contrast by 1, no software does so via this software interrupt.
Called via INT [50h]
This restores startup contrast from $2000. Contents of B are lost.
When accessing LCD commands like this, it’s a good idea to disable interrupts (other than ones leading to a system shutdown).
No official software uses this.
Called via:
INT [52h]
; startup contrast is now in A
No official software uses this. Instead, [MINLIB][] provides a method for this (TODO: link?) which respects the different location of the startup contrast on a development rig.
Called via:
LD A, #(new contrast)
INT [54h]
; contents of B lost
We call this “temporary” because 50h is able to restore the startup, which this doesn’t edit. A can be 0~63 (inclusive) where 0 is fully white and 63 is fully black. The startup contrast set by the bios is 31 (50%). The LCD panel itself normally defaults to 32.
When accessing LCD commands like this, it’s a good idea to disable interrupts (other than ones leading to a system shutdown).
Official software which uses this:
Called via INT [56h]
Turns the LCD on safely. Disables/restores interrupts around doing so. The contents of BA are lost.
There is some code in here which is currently unclear, please contribute if you figure it out!
Official software which uses this:
In previous documentation, this was known as “initialize LCD”.
Called via INT [58h]
Restores the LCD to its default state. Only works if the LCD is on, NOP otherwise. The contents of BA are lost.
No official software uses this.
Called via INT [5Ah]
Turns the LCD off safely. This also turns off frame copy, which you will need to re-enable manually after turning the LCD on.
No official software uses this.
These will be renamed. “RAM vector” is not really accurate. In previous documentation, this was known as “enable RAM vector”.
Called via INT [5Ch]
If bit 7 of $2001 is unset, sets bits 7~6 and resets bit 5, which sets the console as “asleep”, which will cause IRQs to follow the wake up pathway.
It’s possible this is useful for hotswapping cartridges, but would need some setup before the INT operation.
No official software uses this.
These will be renamed. “RAM vector” is not really accurate. In previous documentation, this was known as “disable RAM vector”.
Called via INT [5Eh]
If bit 6 of $2001 is unset, prepares cart eject, resets bits 7~6, and sets bit 5, which will cause IRQs to stop following wake up pathway
No official software uses this.
These will be renamed. In previous documentation, this was known as “disable cart eject IRQ 13 (with abort)” or “dis_irq_13” where $13 is the previously used index for the cart eject IRQ.
Called via INT [60h]
TODO:
No official software uses this.
These will be renamed. In previous documentation, this was known as “enable cart eject IRQ 13 (with abort)” or “ena_irq_13” where $13 is the previously used index for the cart eject IRQ.
Called via INT [62h]
TODO:
No official software uses this.
These will be renamed.
Called via INT [64h]
TODO:
No official software uses this.
These will be renamed.
Called via INT [66h]
TODO:
No official software uses this.
These will be renamed.
Called via:
INT [68h]
OR A, A
JRS Z, success
; contents of B/XP lost
Turns on the cartidge power (if one is inserted) and prepares the selected game from the multicart. In the event of an error, the cartridge slot is unpowered (if it was previously unpowered).
A returns the result of this routine. 0 for success, 1 for no cart inserted, or 2 for some other error.
The purpose of this code is currently unclear, please contribute if you figure it out!
No official software uses this.
These will be renamed.
Called via:
INT [6Ah]
OR A, A
JRS Z, success
; contents of B/XP lost
Similar to 68h but with less checks. Cart power stays on even if there’s an error.
A returns the result of this routine. 0 for success, 1 for no cart inserted, or -1 if the startup action is 0 or 2 (or this isn’t a dev cart at all).
No official software uses this.
Called via:
LD A, #(cart eject IRQ priority)
INT [6Ch]
; contents of B lost
No official software uses this.
Called via INT [6Eh]
No official software uses this.
Called via:
INT [70h]
OR A, A
JRS Z, fired
This checks if the current interrupt priority in I1~I0 is equal to the cart eject priority, and if so returns whether or not it fired (and clears it). This is not how IRQ priority normally works: it normally checks that the priority is strictly greater than the interrupt flags.
No official software uses this. Not sure anything should…
Called via INT [72h]
This causes the PM to enter normal operation mode, clocking the CPU off of OSC3 instead of OSC1. This is the default state when exiting the BIOS, so it only ever needs to be called if 74h is ever used.
No official software uses this.
Called via INT [74h]
This causes the PM to enter low power operation mode, clocking the CPU off of OSC1 instead of OSC3. This saves power but limits the capabilities of the PM.
TODO: discussion of limitations
No official software uses this.
Called via INT [76h]
Also resets bit 6 of [$2002]. TODO: why?
No official software uses this.
Called via INT [78h]
Also sets bits 7~6 of [$2002]. TODO: why?
No official software uses this.
Called via:
INT [7Ah]
OR A, A
JRS Z, inserted
No official software uses this.
In previous documentation, this was known as “set PRC rate”.
Called via:
LD A, #(frame rate divider index)
INT [7Eh]
While the frame rate divider can have a value of 0~7 it’s not the divisor itself, it corresponds like this:
| Index | Divider | FPS |
| —– | ——-: | —: |
| 0 | 3 | 24 |
| 1 | 6 | 12 |
| 2 | 9 | 8 |
| 3 | 12 | 6 |
| 4 | 2 | 36 |
| 5 | 4 | 18 |
| 6 | 6 | 12 |
| 7 | 8 | 9 |
All official software uses this:
In previous documentation, this was known as “get PRC rate”.
Called via:
INT [80h]
; frame rate divider index in A
See above for the table converting an index to an actual divisor.
Official software which uses this:
In previous documentation, this was known as “test cart type”.
Called via:
INT [82h]
JRS NZ, multicart
If this returns Z=0, it means bits 2~0 of $2001 represent a valid game ID in an official multicart set up. Z=1 doesn’t mean it’s not an official multicart set up, it could mean that it didn’t use the game select screen or that it’s a release game/unsupported flash cart/etc.
No official software uses this.
Called via:
LD XP, #(final data page in external page)
LD A, #(bank ID)
INT [8Eh]
Use this to map a single bank. If you need to map multiple, use enter bank select mode instead. To configure page 0, unlock that capability first.
See here for the table mapping external page index to internal pages.
The BIOS uses this several times to remap bank 0 to page 1, making bytes $0000~$2100 (exclusive) accessible for reading and code execution. Of course, it also uses this to undo that mapping.
No other official software uses this.
Called via:
LD A, #(game ID in ROM's struct array)
INT [94h]
; contents of B lost
The BIOS uses this to prepare any game stored in this multi-rom format, even when not using the game select screen.
No other official software uses this.
This is not a software interrupt, but a value which is checked by MINLIB to conditionalize execution in some instances. In the official BIOS the value here is 0x0000.
TODO: where/how is it checked, what does it change
Called via:
LD YP, #00h
LD IY, #2061h
LD B, #(pulse time)
INT [98h]
; contents of B lost
The pulse time is in CPU cycles * 4. Official software only uses #04h for this value, meaning it pulses for 16 CPU cycles then uses a NOP slide for an off pulse. For more, see the IR page.
Official software which uses this:
The BIOS can initialize from two points which we call a soft reset and a hard reset. A soft reset is when you wake up the console from sleeping. It goes to sleep when you push the power button while running a game, and reawakens if you push the power button again. A hard reset is when you remove the battery and reinsert it. TODO: what does the reset button do
This represents the initial startup sequence for initializing the LCD. When turning the LCD on manually via INT [56h] the sequence has some slight differences.
Note that the required voltage was set earlier here, which is likely looking for 3.3V but the exact voltage is unknown.
For information on the dev cart, see here
For the Game Select screen, see here
Checks for NINTENDO existing at $21A4 in cartridge ROM. The string it compares against is stored at $0E1A
If the check fails, it goes to the Insert cartridge screen.
The screen graphics and tilemaps are compressed and stored here with their animation data stored here.
To extract the graphics yourself, you may use the tool provided here
The compression uses a simple RLE compression algorithm:
The graphics data is loaded to $1530 all at once (it does not load the screen graphics on demand) here. The tilemaps start at $1650 and the tiles start at $1830. $1530 itself is a blank tilemap. These tilemaps are 5 rows of 12 tiles each, so slightly shorter than the full screen but the full width. When displayed, they’re vertically centered onto the screen.
The play animation routine first loads the blank tilemap to clear the screen, then reads the animation description in order to load the specific screen.
The animation description uses the following format:
Frames are in reverse order, that is: Frame N, …, Frame 1, Frame 0. The animation repeats until the total play time specified in the footer is reached, then it shuts off the unit.
The animation data contains 20 bytes + the footer and specifies a play time of 408 rendered frames. The frames decode to:
| Frame | Len | Addr |
|---|---|---|
| 9 | 9 | $0B4 |
| 8 | 9 | $0F0 |
| 7 | 9 | $12C |
| 6 | 9 | $168 |
| 5 | 9 | $1A4 |
| 4 | 9 | $168 |
| 3 | 9 | $1A4 |
| 2 | 9 | $168 |
| 1 | 9 | $1A4 |
| 0 | 55 | $168 |
The animation data contains 6 bytes + the footer and specifies a play time of 288 rendered frames. The frames decode to:
| Frame | Len | Addr |
|---|---|---|
| 2 | 30 | $000 |
| 1 | 12 | $03C |
| 0 | 6 | $078 |
A screen showcasing a game selection menu. It has no animations but is rather an interactive menu. A portion of this menu is preloaded but some is dynamically loaded once the BIOS decides it needs it.
The game names are pulled from the cartridge as 9 raw tile graphics, allowing for any styling of the name.
The menu GUI is a simple scrolling list. It starts at the top and allows the user to scroll down for 8 lines, displaying only 5 at a time. If an entry is off-screen, arrows indicate there are more above and/or below the current view.