Pokémon mini Development Documentation

BIOS

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!

Interrupt vector table

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.

Software interrupts

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 Enable RAM vector
5Eh $0904 Disable RAM vector
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.

Software-defined interrupt

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.

Suspend system

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:

Sleep

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:

Sleep with display on

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.

Shutdown system

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:

Set startup LCD contrast

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:

Step & apply startup contrast

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.

Apply startup LCD contrast

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.

Get startup contrast

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.

Set temporary LCD contrast

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:

Turn LCD on

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:

Reset LCD

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.

Turn LCD off

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.

5Ch

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.

5Eh

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.

60h

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.

62h

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.

64h

These will be renamed.

Called via INT [64h]

TODO:

No official software uses this.

66h

These will be renamed.

Called via INT [66h]

TODO:

No official software uses this.

68h

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.

6Ah

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.

Enable cart eject IRQ and set priority

Called via:

LD A, #(cart eject IRQ priority)
INT [6Ch]
; contents of B lost

No official software uses this.

Disable cart eject IRQ

Called via INT [6Eh]

No official software uses this.

Check cart eject fired

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…

Enter normal operation

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.

Enter low power operation

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.

Power off cart slot

Called via INT [76h]

Also resets bit 6 of [$2002]. TODO: why?

No official software uses this.

Power on cart slot

Called via INT [78h]

Also sets bits 7~6 of [$2002]. TODO: why?

No official software uses this.

Check cart is inserted

Called via:

INT [7Ah]
OR A, A
JRS Z, inserted

No official software uses this.

7Ch

Set frame rate divider

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:

Get frame rate divider

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:

Valid multicart game index

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.

Flash cart commands

Select individual bank

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.

Prepare game

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.

96h

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

IR pulse

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:

Initialization

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

  1. Hard reset exclusive initialization
  2. Initialize registers, CPU, peripherals
  3. Decompress screens’ data
  4. If there’s no cartridge, go to the insert cartridge screen
  5. Low battery check
  6. Check if it’s a development cartridge
  7. Run a copyright check
  8. Boot software

Hard reset exclusive initialization

  1. Reset and enable seconds counter
  2. Set screen contrast to 50%
  3. Reset RTC (TODO: re-evaluate)

Initialize registers, CPU, peripherals

  1. (soft reset) Initialize registers & CPU
  2. Store startup keypad state to $14E1
  3. Enable and power cartridge slot
  4. Initialize voltage detector criteria ->
  5. Enable oscillators
  6. Configure IRQs to defaults
  7. Initialize I/O
  8. Initialize LCD controller
  9. Initialize cartridge
  10. Enable exception handling globally (priority 3 only)
  11. Initialize LCD

LCD

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.

  1. Clear LCD display RAM ->
  2. Read contrast from register $00 and send it to the LCD driver ->
  3. Disable LCD controller
  4. Send NOP
  5. Send setall off
  6. Send static indicator on and blink at half seconds
  7. Send end
  8. Send set display start line 0
  9. Send ADC select normal
  10. Send row direction normal
  11. Send color invert off
  12. Send power control all on
  13. wait 349980 cycles (TODO: ms) ->
  14. Send display on

Low battery check

Jump to code

  1. Turns on the SVD circuit
  2. Waits 200 cycles (docs require >= 100 µs)
  3. Turns off the SVD to load the result into SVDDT
  4. Reads SVDDT and goes to the low battery screen if it’s a 1 (indicating the voltage is low)

Note that the required voltage was set earlier here, which is likely looking for 3.3V but the exact voltage is unknown.

Development cartridge

For information on the dev cart, see here

For the Game Select screen, see here

Jump to code

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.

Boot software

  1. Initialize LCD controller for software ->
  2. Reinitialize registers -> ->
  3. Clear RAM (all $00) ->
  4. Store startup keypad state in B and cart type in A -> ->
  5. Disable exception handling globally ->
  6. Jump to game entry point ->

Screens

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.

Insert cartridge screen

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

Low battery screen

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

Game Select screen

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.