path: root/Optimizing-assembly-code.md

Sometimes the simplest way to write something in assembly code isn't the best. All of your resources are limited: CPU speed, ROM size, RAM space, register use. You can rewrite code to use those resources more efficiently (sometimes by trading one for another).

Most of these tricks come from [Jeff's GB Assembly Code Tips v1.0](http://www.devrs.com/gb/files/asmtips.txt), [WikiTI's Z80 Optimization page](http://wikiti.brandonw.net/index.php?title=Z80_Optimization), and [z80 Heaven's optimization tutorial](http://z80-heaven.wikidot.com/optimization). (Note that Z80 assembly is *not* the same as GBZ80; it has more registers and some different instructions.)

WikiTI's advice fully applies here:

> Note that the following tricks act much like a [peephole optimizer](https://en.wikipedia.org/wiki/Peephole_optimization) and are the last optimization step: remember to first optimize your algorithm and register allocation before applying any of the following if you really want the fastest speed and the smallest code.
>
> Also note that nearly every trick turns the code less understandable and documenting them is a good idea. You can easily forgot after a while without reading parts of the code.
>
> Be warned that some tricks are not exactly equivalent to the normal way and may have exceptions on their use; comments warn about them. Some tricks apply to other cases, but again you have to be careful.
>
> There are some tricks that are nothing more than the correct use of the available instructions on the Z80. Keeping an [instruction set summary](https://rednex.github.io/rgbds/gbz80.7.html) helps to visualize what you can do during coding.

(There's also a "cheat sheet" [table of instructions](https://gbdev.io/gb-opcodes//optables/classic) summarizing their bytes, cycles, and affected flags, if you don't need a long listing of what each one does.)


## Contents

- [8-bit registers](#8-bit-registers)
  - [Set `a` to 0](#set-a-to-0)
  - [Increment or decrement `a`](#increment-or-decrement-a)
  - [Invert the bits of `a`](#invert-the-bits-of-a)
  - [Rotate the bits of `a`](#rotate-the-bits-of-a)
  - [Reverse the bits of `a`](#reverse-the-bits-of-a)
  - [Set `a` to some constant minus `a`](#set-a-to-some-constant-minus-a)
  - [Set `a` to one constant or another depending on the carry flag](#set-a-to-one-constant-or-another-depending-on-the-carry-flag)
  - [Increment or decrement `a` when the carry flag is set](#increment-or-decrement-a-when-the-carry-flag-is-set)
  - [Divide `a` by 8 (shift `a` right 3 bits)](#divide-a-by-8-shift-a-right-3-bits)
  - [Divide `a` by 16 (shift `a` right 4 bits)](#divide-a-by-16-shift-a-right-4-bits)
  - [Set `a` to some value plus carry](#set-a-to-some-value-plus-carry)
  - [Load from HRAM to `a` or from `a` to HRAM](#load-from-hram-to-a-or-from-a-to-hram)
- [16-bit registers](#16-bit-registers)
  - [Multiply `hl` by 2](#multiply-hl-by-2)
  - [Add `a` to a 16-bit register](#add-a-to-a-16-bit-register)
  - [Subtract an 8-bit constant from a 16-bit register](#subtract-an-8-bit-constant-from-a-16-bit-register)
  - [Set a 16-bit register to `a` plus a 16-bit constant](#set-a-16-bit-register-to-a-plus-a-16-bit-constant)
  - [Set a 16-bit register to `a` \* 16](#set-a-16-bit-register-to-a--16)
  - [Increment or decrement a 16-bit register](#increment-or-decrement-a-16-bit-register)
  - [Load from an address to `hl`](#load-from-an-address-to-hl)
  - [Exchange two 16-bit registers](#exchange-two-16-bit-registers)
  - [Load two constants into a register pair](#load-two-constants-into-a-register-pair)
  - [Load a constant into `[hl]`](#load-a-constant-into-hl)
  - [Increment or decrement `[hl]`](#increment-or-decrement-hl)
  - [Load a constant into `[hl]` and increment or decrement `hl`](#load-a-constant-into-hl-and-increment-or-decrement-hl)
- [Branching (control flow)](#branching-control-flow)
  - [Relative jumps](#relative-jumps)
  - [Compare `a` to 0](#compare-a-to-0)
  - [Compare `a` to 1](#compare-a-to-1)
  - [Compare `a` to 255](#compare-a-to-255)
  - [Compare `a` to 0 after masking it](#compare-a-to-0-after-masking-it)
  - [Test whether `a` is negative (compare `a` to $80)](#test-whether-a-is-negative-compare-a-to-80)
- [Subroutines (functions)](#subroutines-functions)
  - [Tail call optimization](#tail-call-optimization)
  - [Call `hl`](#call-hl)
  - [Inlining](#inlining)
  - [Fallthrough](#fallthrough)
  - [Conditional fallthrough](#conditional-fallthrough)
  - [Call `rst $38` depending on a flag](#call-rst-38-depending-on-a-flag)
- [Jump and lookup tables](#jump-and-lookup-tables)
  - [Chain comparisons](#chain-comparisons)


## 8-bit registers


### Set `a` to 0

Don't do:

```asm
	ld a, 0 ; 2 bytes, 2 cycles, no changes to flags
```

But do:

```asm
	xor a ; 1 byte, 1 cycle, sets flags C to 0 and Z to 1
```

Or do:

```asm
	sub a ; 1 byte, 1 cycle, sets flags C to 0 and Z to 1
```

Don't use the optimized versions if you need to preserve flags. As such, `ld a, 0` must be left intact in the code below:

```asm
	ld a, [wIsTrainerBattle]
	and a   ; sets flag Z if [wIsTrainerBattle] is 0
	ld a, 0 ; sets a to 0 without affecting Z
	jr nz, .is_trainer_battle
```


### Increment or decrement `a`

When possible, avoid doing:

```asm
	add 1 ; 2 bytes, 2 cycles; sets carry for -1 to 0 overflow
```

```asm
	sub 1 ; 2 bytes, 2 cycles; sets carry for 0 to -1 underflow
```

If you don't need to set the carry flag, then do:

```asm
	inc a ; 1 byte, 1 cycle
```

```asm
	dec a ; 1 byte, 1 cycle
```


### Invert the bits of `a`

Don't do:

```asm
	xor $ff ; 2 bytes, 2 cycles
```

But do:

```asm
	cpl ; 1 byte, 1 cycle
```


### Rotate the bits of `a`

Don't do:

```asm
	rl a ; 2 bytes, 2 cycles; updates Z and C flags
```

```asm
	rlc a ; 2 bytes, 2 cycles; updates Z and C flags
```

```asm
	rr a ; 2 bytes, 2 cycles; updates Z and C flags
```

```asm
	rrc a ; 2 bytes, 2 cycles; updates Z and C flags
```

But do:

```asm
	rla ; 1 byte, 1 cycle; updates C flag
```

```asm
	rlca ; 1 byte, 1 cycle; updates C flag
```

```asm
	rra ; 1 byte, 1 cycle; updates C flag
```

```asm
	rrca ; 1 byte, 1 cycle; updates C flag
```

The exception is if you need to set the zero flag when the operation results in 0 for `a`; the two-byte operations can set `z`, the one-byte operations cannot.


### Reverse the bits of `a`

(This optimization is based on [Retro Programming](http://www.retroprogramming.com/2014/01/fast-z80-bit-reversal.html)).

(The example uses `b` and `c`, but any of `d`, `e`, `h`, or `l` would also work.)

Don't do:

```asm
	; 26 bytes, 26 cycles
rept 8
	rra
	rl b
endr
	ld a, b
```

And don't do:

```asm
	; 17 bytes, 17 cycles
	ld b, a
	rlca
	rlca
	xor b
	and $aa
	xor b
	ld b, a
	rlca
	rlca
	rlca
	rrc b
	xor b
	and $66
	xor b
```

But do:

```asm
	; 15 bytes, 15 cycles
	ld b, a
	rlca
	rlca
	xor b
	and $aa
	xor b
	ld b, a
	swap b
	xor b
	and $33
	xor b
	rrca
```

Or if you really want to optimize for size over speed, then do:

```asm
	; 10 bytes, 59 cycles
	ld bc, 8  ; lb bc, 0, 8
.loop
	rra
	rl b
	dec c
	jr nz, .loop
	ld a, b
```


### Set `a` to some constant minus `a`

Don't do:

```asm
	; 4 bytes, 4 cycles
	ld b, a
	ld a, FOOBAR
	sub b
```

But do:

```asm
	; 3 bytes, 3 cycles
	cpl
	add FOOBAR + 1
```

("What's [foobar](https://en.wikipedia.org/wiki/Foobar)?")


### Set `a` to one constant or another depending on the carry flag

(The example sets `a` to `CVAL` if the carry flag is set (`c`), or `NCVAL` is the carry flag is not set (`nc`).)

Don't do:

```asm
	; 6 bytes, 6 or 7 cycles
	ld a, CVAL
	jr c, .carry
	ld a, NCVAL
.carry
```

And don't do:

```asm
	; 6 bytes, 6 or 7 cycles
	ld a, NCVAL
	jr nc, .no_carry
	ld a, CVAL
.no_carry
```

And if either is 0, don't do:

```asm
	; 5 bytes, 5 or 6 cycles
	ld a, CVAL   ; nor NCVAL
	jr c, .carry ; nor jr nc
	xor a
.carry
```

And if either is 1 more or less than the other, don't do:

```asm
	; 5 bytes, 5 or 6 cycles
	ld a, CVAL   ; nor NCVAL
	jr c, .carry ; nor jr nc
	inc a        ; nor dec a
.carry
```

Instead use `sbc a`, which copies the carry flag to all bits of `a`. Thus do:

```asm
	; 5 bytes, 5 cycles
	sbc a            ; if carry, then $ff, else 0
	and CVAL - NCVAL ; $ff becomes CVAL - NCVAL, 0 stays 0
	add NCVAL        ; CVAL - NCVAL becomes CVAL, 0 becomes NCVAL
```

Or do:

```asm
	; 5 bytes, 5 cycles
	sbc a            ; if carry, then $ff, else 0
	and CVAL ^ NCVAL ; $ff becomes CVAL ^ NCVAL, 0 stays 0
	xor NCVAL        ; CVAL ^ NCVAL becomes CVAL, 0 becomes NCVAL
```

And if certain conditions apply, then do something more efficient:

<table>

<tr>
<th>If this...</th>
<th>...then do:</th>
</tr>

<tr><td>

`CVAL` == $FF (aka −1) <br>and<br> `NCVAL` == 0

</td><td>

```asm
	; 1 byte, 1 cycle
	sbc a ; if carry, then $ff, else 0
```

</td></tr>
<tr><td>

`CVAL` == 0 <br>and<br> `NCVAL` == $FF (aka −1)

</td><td>

```asm
	; 2 bytes, 2 cycles
	ccf   ; invert carry flag
	sbc a ; if originally carry, then 0, else $ff
```

</td></tr>
<tr><td>

`CVAL` == 0 <br>and<br> `NCVAL` == 1

</td><td>

```asm
	; 2 bytes, 2 cycles
	sbc a ; if carry, then $ff aka -1, else 0
	inc a ; -1 becomes 0, 0 becomes 1
```

</td></tr>
<tr><td>

`CVAL` == $FF (aka −1)

</td><td>

```asm
	; 3 bytes, 3 cycles
	sbc a     ; if carry, then $ff, else 0
	or NCVAL  ; $ff stays $ff, $00 becomes NCVAL
```

</td></tr>
<tr><td>

`NCVAL` == 0

</td><td>

```asm
	; 3 bytes, 3 cycles
	sbc a    ; if carry, then $ff, else 0
	and CVAL ; $ff becomes CVAL, 0 stays 0
```

</td></tr>
<tr><td>

`CVAL` == `NCVAL - 1`, <br>aka<br> `CVAL + 1` == `NCVAL`

</td><td>

```asm
	; 3 bytes, 3 cycles
	sbc a     ; if carry, then $ff aka -1, else 0
	add NCVAL ; -1 becomes NCVAL - 1 aka CVAL, 0 becomes NCVAL
```

</td></tr>
<tr><td>

`CVAL` == `NCVAL - 2`, <br>aka<br> `CVAL + 2` == `NCVAL`

</td><td>

```asm
	; 3 bytes, 3 cycles
	sbc a      ; if carry, then $ff aka -1, else 0; doesn't change the carry flag
	sbc -NCVAL ; -1 becomes NCVAL - 2 aka CVAL, 0 becomes NCVAL
```

</td></tr>
<tr><td>

`CVAL` == 0

</td><td>

```asm
	; 4 bytes, 4 cycles
	ccf       ; invert carry flag
	sbc a     ; if originally carry, then 0, else $ff
	and NCVAL ; 0 stays 0, $ff becomes NCVAL
```

</td></tr>
<tr><td>

`NCVAL` == $FF (aka −1)

</td><td>

```asm
	; 4 bytes, 4 cycles
	ccf     ; invert carry flag
	sbc a   ; if originally carry, then 0, else $ff
	or CVAL ; $00 becomes CVAL, $ff stays $ff
```

</td></tr>
<tr><td>

`CVAL` == `NCVAL + 1`, <br>aka<br> `CVAL - 1` == `NCVAL`

</td><td>

```asm
	; 4 bytes, 4 cycles
	ccf      ; invert carry flag
	sbc a    ; if originally carry, then 0, else $ff aka -1
	add CVAL ; -1 becomes CVAL - 1 aka NCVAL, 0 becomes CVAL
```

</td></tr>
<tr><td>

`CVAL` == `NCVAL + 2`, <br>aka<br> `CVAL - 2` == `NCVAL`

</td><td>

```asm
	; 4 bytes, 4 cycles
	ccf       ; invert carry flag
	sbc a     ; if carry, then 0, else $ff aka -1; doesn't change the carry flag
	sbc -CVAL ; -1 becomes CVAL - 2 aka NCVAL, 0 becomes CVAL
```

</td></tr>

</table>


### Increment or decrement `a` when the carry flag is set

Don't do:

```asm
	; 3 bytes, 3 cycles
	jr nc, .ok
	inc a
.ok
```

```asm
	; 3 bytes, 3 cycles
	jr nc, .ok
	dec a
.ok
```

But do:

```asm
	adc 0 ; 2 bytes, 2 cycles
```

```asm
	sbc 0 ; 2 bytes, 2 cycles
```


### Divide `a` by 8 (shift `a` right 3 bits)

Don't do:

```asm
	; 6 bytes, 9 cycles
	; (15 bytes, at least 21 cycles, counting the definition of SimpleDivide)
	ld c, 8 ; divisor
	call SimpleDivide
	ld a, b ; quotient
```

And don't do:

```asm
	; 6 bytes, 6 cycles
	srl a
	srl a
	srl a
```

But do:

```asm
	; 5 bytes, 5 cycles
	rrca
	rrca
	rrca
	and %00011111
```


### Divide `a` by 16 (shift `a` right 4 bits)

Don't do:

```asm
	; 6 bytes, 9 cycles
	; (15 bytes, at least 21 cycles, counting the definition of SimpleDivide)
	ld c, 16 ; divisor
	call SimpleDivide
	ld a, b ; quotient
```

And don't do:

```asm
	; 8 bytes, 8 cycles
	srl a
	srl a
	srl a
	srl a
```

But do:

```asm
	; 4 bytes, 4 cycles
	swap a
	and $f
```


### Set `a` to some value plus carry

(The example uses `b` and `c`, but any registers besides `a` would also work, including `[hl]`.)

Don't do:

```asm
	; 4 bytes, 4 cycles
	ld b, a
	ld a, c
	adc 0
```

And don't do:

```asm
	; 4 bytes, 4 cycles
	ld b, a
	ld a, 0
	adc c
```

But do:

```asm
	; 3 bytes, 3 cycles
	ld b, a
	adc c
	sub b
```

Also, don't do:

```asm
	; 5 bytes, 5 cycles
	ld b, a
	ld a, N
	adc 0
```

And don't do:

```asm
	; 5 bytes, 5 cycles
	ld b, a
	ld a, 0
	adc N
```

But do:

```asm
	; 4 bytes, 4 cycles
	ld b, a
	adc N
	sub b
```


### Load from HRAM to `a` or from `a` to HRAM

Don't do:

```asm
	ld a, [hFoo] ; 3 bytes, 4 cycles
```

```asm
	ld [hFoo], a ; 3 bytes, 4 cycles
```

But do:

```asm
	ldh a, [hFoo] ; 2 bytes, 3 cycles
```

```asm
	ldh [hFoo], a ; 2 bytes, 3 cycles
```


## 16-bit registers


### Multiply `hl` by 2

Don't do:

```asm
	; 4 bytes, 4 cycles
	sla l
	rl h
```

But do:

```asm
	add hl, hl ; 1 byte, 2 cycles
```


### Add `a` to a 16-bit register

(The example uses `hl`, but `bc` or `de` would also work.)

Don't do:

```asm
	; 6 bytes, 6 cycles
	add l
	ld l, a
	ld a, 0
	adc h
	ld h, a
```

and don't do:

```asm
	; 6 bytes, 6 cycles
	add l
	ld l, a
	ld a, h
	adc 0
	ld h, a
```

and don't do:

```asm
	; 5 bytes, 5 or 6 cycles
	add l
	ld l, a
	jr nc, .no_carry
	inc h
.no_carry
```

But do:

```asm
	; 5 bytes, 5 cycles
	add l
	ld l, a
	adc h
	sub l
	ld h, a
```

Or if you can spare another 16-bit register and want to optimize for size over speed, do:

```asm
	; 4 bytes, 5 cycles
	ld d, 0
	ld e, a
	add hl, de
```


### Subtract an 8-bit constant from a 16-bit register

(The example uses `hl`, but `bc` or `de` would also work.)

Don't do:

```asm
	; 8 bytes, 8 cycles
	ld a, l
	sub FOO
	ld l, a
	ld a, h
	sbc 0
	ld h, a
```

But do:

```asm
	; 7 bytes, 7 or 8 cycles
	ld a, l
	sub FOO
	ld l, a
	jr nc, .no_carry
	dec h
.no_carry
```

Or if you can spare another 16-bit register, do:

```asm
	; 4 bytes, 5 cycles
	ld de, -FOO
	add hl, de
```


### Set a 16-bit register to `a` plus a 16-bit constant

(The example uses `hl`, but `bc` or `de` would also work.)

Don't do:

```asm
	; 7 bytes, 8 cycles; uses another 16-bit register
	ld e, a
	ld d, 0
	ld hl, Address
	add hl, de
```

And don't do:

```asm
	; 8 bytes, 8 cycles
	ld hl, Address
	add l
	ld l, a
	adc h
	sub l
	ld h, a
```

And don't do:

```asm
	; 8 bytes, 7 or 8 cycles
	ld h, HIGH(Address)
	add LOW(Address)
	ld l, a
	jr nc, .no_carry
	inc h
.no_carry
```

But do:

```asm
	; 7 bytes, 7 cycles
	add LOW(Address)
	ld l, a
	adc HIGH(Address)
	sub l
	ld h, a
```


### Set a 16-bit register to `a` \* 16

(The example uses `hl`, but `bc` or `de` would also work.)

You can do:

```asm
	; 7 bytes, 11 cycles
	ld l, a
	ld h, 0
	add hl, hl
	add hl, hl
	add hl, hl
	add hl, hl
```

```asm
	; 7 bytes, 11 cycles
	ld l, a
	ld h, 0
rept 4
	add hl, hl
endr
```

But if `a` is definitely small enough, and its value can be changed, then do:

```asm
	; 7 bytes, 10 cycles; sets a = a * 2; requires a < $80
	add a
	ld l, a
	ld h, 0
	add hl, hl
	add hl, hl
	add hl, hl
```

```asm
	; 7 bytes, 9 cycles; sets a = a * 4; requires a < $40
	add a
	add a
	ld l, a
	ld h, 0
	add hl, hl
	add hl, hl
```

```asm
	; 7 bytes, 8 cycles; sets a = a * 8; requires a < $20
	add a
	add a
	add a
	ld l, a
	ld h, 0
	add hl, hl
```

```asm
	; 5 bytes, 5 cycles; sets a = a * 16; requires a < $10
	swap a
	ld l, a
	ld h, 0
```

Or if the value of `a` can be changed and you want to optimize for speed over size, do:

```asm
	; 8 bytes, 8 cycles; sets a = l
	swap a
	ld l, a
	and $f
	ld h, a
	xor l
	ld l, a
```

Or do:

```asm
	; 8 bytes, 8 cycles; sets a = h
	swap a
	ld h, a
	and $f0
	ld l, a
	xor h
	ld h, a
```


### Increment or decrement a 16-bit register

When possible, avoid doing:

```asm
	inc hl ; 1 byte, 2 cycles
```

```asm
	dec hl ; 1 byte, 2 cycles
```

If the low byte *definitely* won't overflow, then do:

```asm
	inc l ; 1 byte, 1 cycle
```

```asm
	dec l ; 1 byte, 1 cycle
```

This is applicable, for instance, if you're reading a data table via `hl` one byte at a time, it has no more than 256 entries, and it's in its own `SECTION` which has been `ALIGN`ed to 8 bits. It's unlikely to apply to pokecrystal's existing systems.


### Load from an address to `hl`

Don't do:

```asm
	; 8 bytes, 10 cycles
	ld a, [Address]  ; LSB first
	ld l, a
	ld a, [Address+1]
	ld h, a
```

But do:

```asm
	; 6 bytes, 8 cycles
	ld hl, Address
	ld a, [hli]
	ld h, [hl]
	ld l, a
```

And don't do:

```asm
	; 8 bytes, 10 cycles
	ld a, [Address]  ; MSB first
	ld h, a
	ld a, [Address+1]
	ld l, a
```

But do:

```asm
	; 6 bytes, 8 cycles
	ld hl, Address
	ld a, [hli]
	ld l, [hl]
	ld h, a
```


### Exchange two 16-bit registers

(The example uses `hl` and `de`, but any pair of `bc`, `de`, or `hl` would also work.)

If you care about speed:

```asm
	; 6 bytes, 6 cycles
	ld a, d
	ld d, h
	ld h, a
	ld a, e
	ld e, l
	ld l, a
```

If you care about size:

```asm
	; 4 bytes, 9 cycles
	push de
	ld d, h
	ld e, l
	pop hl
```


### Load two constants into a register pair

(The example uses `bc`, but `hl` or `de` would also work.)

Don't do:

```asm
	; 4 bytes, 4 cycles
	ld b, FOO
	ld c, BAR
```

But do:

```asm
	ld bc, FOO << 8 | BAR ; 3 bytes, 3 cycles
```

Or better, use the `lb` macro in [macros/code.asm](../blob/master/macros/code.asm):

```asm
	lb bc, FOO, BAR ; 3 bytes, 3 cycles
```


### Load a constant into `[hl]`

Don't do:

```asm
	; 3 bytes, 4 cycles
	ld a, FOOBAR
	ld [hl], a
```

But do:

```asm
	ld [hl], FOOBAR ; 2 bytes, 3 cycles
```


### Increment or decrement `[hl]`

Don't do:

```asm
	; 3 bytes, 5 cycles
	ld a, [hl]
	inc a
	ld [hl], a
```

```asm
	; 3 bytes, 5 cycles
	ld a, [hl]
	dec a
	ld [hl], a
```

But do:

```asm
	inc [hl] ; 1 bytes, 3 cycles
```

```asm
	dec [hl] ; 1 bytes, 3 cycles
```


### Load a constant into `[hl]` and increment or decrement `hl`

Don't do:

```asm
	; 2 bytes, 4 cycles
	ld [hl], a
	inc hl
```

```asm
	; 2 bytes, 4 cycles
	ld [hl], a
	dec hl
```

But do:

```asm
	ld [hli], a ; 1 bytes, 2 cycles
```

```asm
	ld [hld], a ; 1 bytes, 2 cycles
```


## Branching (control flow)


### Relative jumps

Don't do:

```asm
	jp Somewhere ; 3 bytes, 4 cycles
```

But do:

```asm
	jr Somewhere ; 2 bytes, 3 cycles
```

This only applies if `Somewhere` is within ±127 bytes of the jump.


### Compare `a` to 0

Don't do:

```asm
	cp 0 ; 2 bytes, 2 cycles
```

And don't do:

```asm
	or 0 ; 2 bytes, 2 cycles
```

And don't do:

```asm
	and $ff ; 2 bytes, 2 cycles
```

But do:

```asm
	or a ; 1 byte, 1 cycle
```

Or do:

```asm
	and a ; 1 byte, 1 cycle
```


### Compare `a` to 1

```asm
	cp 1 ; 2 bytes, 2 cycles
```

If you don't care about carry or the value in `a`:


```asm
	dec a ; 1 byte, 1 cycle, decrements a
```

Note that you can still do `inc a` afterwards, which is one cycle faster if the jump is taken. Compare:

```asm
	cp 1
	jr z, .equals1
```

with:

```asm
	dec a
	jr z, .equals1
	inc a
```


### Compare `a` to 255

(255, or $FF in hexadecimal, is the same as −1 due to [two's complement](https://en.wikipedia.org/wiki/Two%27s_complement).)

```asm
	cp $ff ; 2 bytes, 2 cycles
```

If you don't care about carry or the value in `a`:

```asm
	inc a ; 1 byte, 1 cycle, increments a
```

Note that you can still do `dec a` afterwards, which is one cycle faster if the jump is taken. Compare:

```asm
	cp $ff
	jr z, .equals255
```

with:

```asm
	inc a
	jr z, .equals255
	dec a
```


### Compare `a` to 0 after masking it

Don't do:

```asm
	; 3 bytes, 3 cycles; sets zero flag if a == 0
	and MASK
	and a
```

But do:

```asm
	and MASK ; 2 bytes, 2 cycles; sets zero flag if a == 0
```


### Test whether `a` is negative (compare `a` to $80)

If you don't need to preserve the value in `a`, then don't do:

```asm
	; 4 bytes, 4/5 cycles
	cp $80
	jr nc, .negative
```

And don't do:

```asm
	; 4 bytes, 4/5 cycles
	bit 7, a
	jr nz, .negative
```

Instead, do:

```asm
	; 3 bytes, 3/4 cycles
	rlca
	jr c, .negative
```


## Subroutines (functions)


### Tail call optimization

Don't do:

```asm
	; 4 bytes, 10 cycles
	call Function
	ret
```

But do:

```asm
	jp Function ; 3 bytes, 4 cycles
```


### Call `hl`

Don't do:

```asm
	; 5 bytes, 8 cycles
	(some code)
	ld de, .return
	push de
	jp hl

.return:
	(some more code)
```

But do:

```asm
	; 3 bytes, 6 cycles
	; (4 bytes, 7 cycles, counting the definition of _hl_)
	(some code)
	call _hl_
	(some more code)
```

`_hl_` is a routine already defined in [home/call_regs.asm](../blob/master/home/call_regs.asm):

```asm
_hl_::
	jp hl
```


### Inlining

Don't do:

```asm
	; 4 additional bytes, 10 additional cycles
	call GetOffset
	...

GetOffset:
	(some code)
	ret
```

if `GetOffset` is only called a handful of times. Instead, do:

```asm
; GetOffset
	(some code)
```

You can set `(some code)` apart with blank lines and put a comment on top to make its self-contained nature clear without the extra `call` and `ret`.


### Fallthrough

Don't do:

```asm
	...
	call Function
	ret

Function:
	(some code)
	ret
```

And don't do:

```asm
	...
	jp Function

Function:
	(some code)
	ret
```

But do:

```asm
	...
	; fallthrough
Function:
	(some code)
	ret
```

Fallthrough is what you get when you combine inlining with tail calls.  You can still `call Function` elsewhere, but one tail call can be optimized into a fallthrough.


## Conditional fallthrough

(The example uses `z`, but `nz`, `c`, or `nc` would also work.)

Don't do:

```asm
	(some code)
	jr z, .foo
	jr .bar

.foo
	(foo code)

.bar
	(bar code)
```

But do:

```asm
	(some code)
	jr nz, .bar
	; fallthrough
.foo
	(foo code)

.bar
	(bar code)
```


### Call `rst $38` depending on a flag

(The example uses `z`, but `nz`, `c`, or `nc` would also work.)

Don't do:

```asm
	; 5 bytes, 3 or 14 cycles
	call z, RstVector38
	...

RstVector38:
	rst $38
	ret
```

And don't do:

```asm
	; 3 bytes, 3 or 6 cycles
	jr nz, .no_rst_38
	rst $38
.no_rst_38
	...
```

But do:

```asm
	; 2 bytes, 2 or 7 cycles
	jr z, @ + 1 ; the byte for @ + 1 is $ff, which is the opcode for rst $38
	...
```

(The label `@` evaluates to the current `pc` value, which in `jr z, @ + 1` is right before the `jr` instruction. The instruction consists of two bytes, the opcode and the relative offset. `@ + 1` evaluates to in-between those two bytes. The `jr` instruction encodes its offset relative to the *end* of the instruction, i.e. the *next* `pc` value after the instruction has been read, so the relative offset is `-1`, aka `$ff`.)


## Jump and lookup tables


### Chain comparisons

Don't do:

```asm
	cp 1
	jr z, .equals1
	cp 2
	jr z, .equals2
	cp 3
	jr z, .equals3
	...
```

But do:

```asm
	dec a
	jr z, .equals1
	dec a
	jr z, .equals2
	dec a
	jr z, .equals3
	...
```

Or do:

```asm
	dec a
	ld hl, .jumptable
	ld e, a
	ld d, 0
	add hl, de
	add hl, de
	ld a, [hli]
	ld h, [hl]
	ld l, a
	jp hl

.jumptable:
	dw .equals1
	dw .equals2
	dw .equals3
	...
```

Or better, do:

```asm
	dec a
	ld hl, .jumptable
	rst JumpTable
	...

.jumptable:
	dw .equals1
	dw .equals2
	dw .equals3
	...
```