Jump table

A jump table is a table of code addresses, meant to be indexed by a selector value. For example, a game script might specify an action to be performed via an index, which is then used to select a routine from a jump table of available scripting actions. The alternative to a jump table is a long string of comparisons with each possible selector value. This approach is tedious to set up and maintain, and slow:

; Jumps to routine selected by A
do_action:
       cmp #0
       bne not0
       jmp action0
not0:  cmp #1
       bne not1
       jmp action1
not1:  cmp #2
       bne not2
       jmp action2
not2:  ...

Indirect jumping

The NES doesn't have a JMP (addr,X) instruction, as other members of the 65xx family do. If it had one, a jump table would be trivial to implement, as in the following 65C02/Hu6280/65C816 code:

; Jumps to routine selected by A, from 0 to 127. High bit of A is ignored.
do_action:
       asl a           ; A = A * 2
       tax
       jmp (table,x)

table:
       .word action0, action1, action2 ; ...

The NES does support a JMP (addr) instruction, so a jump table can be implemented by copying the address to a temporary variable, then jumping through it:

; Jumps to routine selected by A, from 0 to 127. High bit of A is ignored.
do_action:
       asl a
       tax
       lda table,x
       sta temp
       lda table+1,x
       sta temp+1
       jmp (temp)

To call a routine via a selector, load the selector into A, then JSR do_action. This will then JMP to the appropriate routine, which will eventually RTS back to the routine that did JSR do_action. Essentially, you have JSR do_action, which then does JMP routine, which then does RTS; the JMP in the middle has no effect on the call stack. Note that the above code cannot be used without a JSR to it, since without that it's just a glorified JMP. That is, do_action must never be inlined in the code that uses it; it must always be called with JSR like a normal routine.

Like most temporary variables, the temp variable in this routine should not be used by both main thread code and an interrupt/NMI. If this routine is interrupted in the middle and the interrupt code modifies temp, the wrong address will be jumped to when it resumes after the interrupt. If a reentrant jump table subroutine is needed, the stack can be used instead (see below).

Stack-based dispatch

Main article: RTS Trick

RTI and RTS allow use of the stack for holding the temporary address. These are normally used to return to some calling/interrupted code, but at their core they pull an address from the stack then jump to it. This is the behavior we need. We push the address on the stack, then execute RTI or RTS to jump to it. It's roundabout, but it solves the interrupt problem.

Even though RTI is meant for returning from an interrupt, it happens to be simpler to use for this technique, since it doesn't adjust the address it pulls from the stack:

do_action:
       asl a
       tax
       lda table+1,x ; high byte first
       pha
       lda table,x
       pha
       php
       rti

RTS is more tricky, because it adds one to the address it pulls from the stack. This requires that every entry in the jump table have one subtracted from it. This could be done by the code, but it's tedious because the low byte must be decremented first, while the high byte needs to be pushed first. Thus, it's preferable to simply subtract one from each entry in the assembly source text:

do_action:
       asl a
       tax
       lda table+1,x
       pha
       lda table,x
       pha
       rts

table:
       .word action0-1, action1-1, action2-1 ; ...

The benefit of the RTS version is that it's three clock cycles faster than the RTI version, due to not having to push the flags. The disadvantage is that you must adjust every table entry by -1.