rgbds/man/gbz80.7

.\" SPDX-License-Identifier: MIT
.\"
.Dd June 30, 2025
.Dt GBZ80 7
.Os
.Sh NAME
.Nm gbz80
.Nd CPU opcode reference
.Sh DESCRIPTION
This is the list of opcodes supported by
.Xr rgbasm 1 ,
including a short description, the number of bytes needed to encode them and the number of CPU cycles at 1MHz (or 2MHz in GBC double speed mode) needed to complete them.
.Pp
Note: All arithmetic and logic instructions that use register
.Sy A
as a destination can omit the destination, since it is assumed to be register
.Sy A
by default.
So the following two lines have the same effect:
.Bd -literal -offset indent
    OR A,B
    OR B
.Ed
.Pp
Furthermore, the
.Sy CPL
instruction can take an optional
.Sy A
destination, since it can only be register
.Sy A .
So the following two lines have the same effect:
.Bd -literal -offset indent
    CPL
    CPL A
.Ed
.Sh LEGEND
List of abbreviations used in this document.
.Bl -tag -width Ds
.It Ar r8
Any of the 8-bit registers
.Pq Sy A , B , C , D , E , H , L .
.It Ar r16
Any of the general-purpose 16-bit registers
.Pq Sy BC , DE , HL .
.It Ar n8
8-bit integer constant
.Po signed or unsigned,
.Sy -128
to
.Sy 255
.Pc .
.It Ar n16
16-bit integer constant
.Po signed or unsigned,
.Sy -32768
to
.Sy 65535
.Pc .
.It Ar e8
8-bit signed offset
.Po Sy -128
to
.Sy 127
.Pc .
.It Ar u3
3-bit unsigned bit index
.Po Sy 0
to
.Sy 7 ,
with
.Sy 0
as the least significant bit
.Pc .
.It Ar cc
A condition code:
.Bl -tag -width Ds -compact
.It Sy Z
Execute if Z is set.
.It Sy NZ
Execute if Z is not set.
.It Sy C
Execute if C is set.
.It Sy NC
Execute if C is not set.
.El
.It Ar vec
An
.Sy RST
vector
.Po Ad 0x00 , 0x08 , 0x10 , 0x18 , 0x20 , 0x28 , 0x30 ,
and
.Ad 0x38 Pc .
.El
.Sh INSTRUCTION OVERVIEW
.Ss Load instructions
.Bl -inset -compact
.It Sx LD r8,r8
.It Sx LD r8,n8
.It Sx LD r16,n16
.It Sx LD [HL],r8
.It Sx LD [HL],n8
.It Sx LD r8,[HL]
.It Sx LD [r16],A
.It Sx LD [n16],A
.It Sx LDH [n16],A
.It Sx LDH [C],A
.It Sx LD A,[r16]
.It Sx LD A,[n16]
.It Sx LDH A,[n16]
.It Sx LDH A,[C]
.It Sx LD [HLI],A
.It Sx LD [HLD],A
.It Sx LD A,[HLI]
.It Sx LD A,[HLD]
.El
.Ss 8-bit arithmetic instructions
.Bl -inset -compact
.It Sx ADC A,r8
.It Sx ADC A,[HL]
.It Sx ADC A,n8
.It Sx ADD A,r8
.It Sx ADD A,[HL]
.It Sx ADD A,n8
.It Sx CP A,r8
.It Sx CP A,[HL]
.It Sx CP A,n8
.It Sx DEC r8
.It Sx DEC [HL]
.It Sx INC r8
.It Sx INC [HL]
.It Sx SBC A,r8
.It Sx SBC A,[HL]
.It Sx SBC A,n8
.It Sx SUB A,r8
.It Sx SUB A,[HL]
.It Sx SUB A,n8
.El
.Ss 16-bit arithmetic instructions
.Bl -inset -compact
.It Sx ADD HL,r16
.It Sx DEC r16
.It Sx INC r16
.El
.Ss Bitwise logic instructions
.Bl -inset -compact
.It Sx AND A,r8
.It Sx AND A,[HL]
.It Sx AND A,n8
.It Sx CPL
.It Sx OR A,r8
.It Sx OR A,[HL]
.It Sx OR A,n8
.It Sx XOR A,r8
.It Sx XOR A,[HL]
.It Sx XOR A,n8
.El
.Ss Bit flag instructions
.Bl -inset -compact
.It Sx BIT u3,r8
.It Sx BIT u3,[HL]
.It Sx RES u3,r8
.It Sx RES u3,[HL]
.It Sx SET u3,r8
.It Sx SET u3,[HL]
.El
.Ss Bit shift instructions
.Bl -inset -compact
.It Sx RL r8
.It Sx RL [HL]
.It Sx RLA
.It Sx RLC r8
.It Sx RLC [HL]
.It Sx RLCA
.It Sx RR r8
.It Sx RR [HL]
.It Sx RRA
.It Sx RRC r8
.It Sx RRC [HL]
.It Sx RRCA
.It Sx SLA r8
.It Sx SLA [HL]
.It Sx SRA r8
.It Sx SRA [HL]
.It Sx SRL r8
.It Sx SRL [HL]
.It Sx SWAP r8
.It Sx SWAP [HL]
.El
.Ss Jumps and subroutine instructions
.Bl -inset -compact
.It Sx CALL n16
.It Sx CALL cc,n16
.It Sx JP HL
.It Sx JP n16
.It Sx JP cc,n16
.It Sx JR n16
.It Sx JR cc,n16
.It Sx RET cc
.It Sx RET
.It Sx RETI
.It Sx RST vec
.El
.Ss Carry flag instructions
.Bl -inset -compact
.It Sx CCF
.It Sx SCF
.El
.Ss Stack manipulation instructions
.Bl -inset -compact
.It Sx ADD HL,SP
.It Sx ADD SP,e8
.It Sx DEC SP
.It Sx INC SP
.It Sx LD SP,n16
.It Sx LD [n16],SP
.It Sx LD HL,SP+e8
.It Sx LD SP,HL
.It Sx POP AF
.It Sx POP r16
.It Sx PUSH AF
.It Sx PUSH r16
.El
.Ss Interrupt-related instructions
.Bl -inset -compact
.It Sx DI
.It Sx EI
.It Sx HALT
.El
.Ss Miscellaneous instructions
.Bl -inset -compact
.It Sx DAA
.It Sx NOP
.It Sx STOP
.El
.Sh INSTRUCTION REFERENCE
.Ss ADC A,r8
Add the value in
.Ar r8
plus the carry flag to
.Sy A .
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
Set if overflow from bit 3.
.It Sy C
Set if overflow from bit 7.
.El
.Ss ADC A,[HL]
Add the byte pointed to by
.Sy HL
plus the carry flag to
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: See
.Sx ADC A,r8
.Ss ADC A,n8
Add the value
.Ar n8
plus the carry flag to
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags: See
.Sx ADC A,r8
.Ss ADD A,r8
Add the value in
.Ar r8
to
.Sy A .
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
Set if overflow from bit 3.
.It Sy C
Set if overflow from bit 7.
.El
.Ss ADD A,[HL]
Add the byte pointed to by
.Sy HL
to
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: See
.Sx ADD A,r8
.Ss ADD A,n8
Add the value
.Ar n8
to
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags: See
.Sx ADD A,r8
.Ss ADD HL,r16
Add the value in
.Ar r16
to
.Sy HL .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy N
0
.It Sy H
Set if overflow from bit 11.
.It Sy C
Set if overflow from bit 15.
.El
.Ss ADD HL,SP
Add the value in
.Sy SP
to
.Sy HL .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: See
.Sx ADD HL,r16
.Ss ADD SP,e8
Add the signed value
.Ar e8
to
.Sy SP .
.Pp
Cycles: 4
.Pp
Bytes: 2
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
0
.It Sy N
0
.It Sy H
Set if overflow from bit 3.
.It Sy C
Set if overflow from bit 7.
.El
.Ss AND A,r8
Set
.Sy A
to the bitwise AND between the value in
.Ar r8
and
.Sy A .
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
1
.It Sy C
0
.El
.Ss AND A,[HL]
Set
.Sy A
to the bitwise AND between the byte pointed to by
.Sy HL
and
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: See
.Sx AND A,r8
.Ss AND A,n8
Set
.Sy A
to the bitwise AND between the value
.Ar n8
and
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags: See
.Sx AND A,r8
.Ss BIT u3,r8
Test bit
.Ar u3
in register
.Ar r8 ,
set the zero flag if bit not set.
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if the selected bit is 0.
.It Sy N
0
.It Sy H
1
.El
.Ss BIT u3,[HL]
Test bit
.Ar u3
in the byte pointed by
.Sy HL ,
set the zero flag if bit not set.
.Pp
Cycles: 3
.Pp
Bytes: 2
.Pp
Flags: See
.Sx BIT u3,r8
.Ss CALL n16
Call address
.Ar n16 .
.Pp
This pushes the address of the instruction after the
.Sy CALL
on the stack, such that
.Sx RET
can pop it later; then, it executes an implicit
.Sx JP n16 .
.Pp
Cycles: 6
.Pp
Bytes: 3
.Pp
Flags: None affected.
.Ss CALL cc,n16
Call address
.Ar n16
if condition
.Ar cc
is met.
.Pp
Cycles: 6 taken / 3 untaken
.Pp
Bytes: 3
.Pp
Flags: None affected.
.Ss CCF
Complement Carry Flag.
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy N
0
.It Sy H
0
.It Sy C
Inverted.
.El
.Ss CP A,r8
ComPare the value in
.Sy A
with the value in
.Ar r8 .
.Pp
This subtracts the value in
.Ar r8
from
.Sy A
and sets flags accordingly, but discards the result.
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
1
.It Sy H
Set if borrow from bit 4.
.It Sy C
Set if borrow (i.e. if
.Ar r8
>
.Sy A ) .
.El
.Ss CP A,[HL]
ComPare the value in
.Sy A
with the byte pointed to by
.Sy HL .
.Pp
This subtracts the byte pointed to by
.Sy HL
from
.Sy A
and sets flags accordingly, but discards the result.
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: See
.Sx CP A,r8
.Ss CP A,n8
ComPare the value in
.Sy A
with the value
.Ar n8 .
.Pp
This subtracts the value
.Ar n8
from
.Sy A
and sets flags accordingly, but discards the result.
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags: See
.Sx CP A,r8
.Ss CPL
ComPLement accumulator
.Po Sy A
=
.Sy ~A 
.Pc ;
also called bitwise NOT.
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy N
1
.It Sy H
1
.El
.Ss DAA
Decimal Adjust Accumulator.
.Pp
Designed to be used after performing an arithmetic instruction
.Pq Sy ADD , ADC , SUB , SBC
whose inputs were in Binary-Coded Decimal (BCD), adjusting the result to likewise be in BCD.
.Pp
The exact behavior of this instruction depends on the state of the subtract flag
.Sy N :
.Bl -tag -width Ds -offset indent
.It If the subtract flag Sy N No is set:
.Bl -enum -compact
.It
Initialize the adjustment to 0.
.It
If the half-carry flag
.Sy H
is set, then add
.Ad $6
to the adjustment.
.It
If the carry flag is set, then add
.Ad $60
to the adjustment.
.It
Subtract the adjustment from
.Sy A .
.El
.It If the subtract flag Sy N No is not set:
.Bl -enum -compact
.It
Initialize the adjustment to 0.
.It
If the half-carry flag
.Sy H
is set or
.Sy A
&
.Ad $F
>
.Ad $9 ,
then add
.Ad $6
to the adjustment.
.It
If the carry flag is set or
.Sy A
>
.Ad $99 ,
then add
.Ad $60
to the adjustment and set the carry flag.
.It
Add the adjustment to
.Sy A .
.El
.El
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy H
0
.It Sy C
Set or reset depending on the operation.
.El
.Ss DEC r8
Decrement the value in register
.Ar r8
by 1.
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
1
.It Sy H
Set if borrow from bit 4.
.El
.Ss DEC [HL]
Decrement the byte pointed to by
.Sy HL
by 1.
.Pp
Cycles: 3
.Pp
Bytes: 1
.Pp
Flags: See
.Sx DEC r8
.Ss DEC r16
Decrement the value in register
.Ar r16
by 1.
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss DEC SP
Decrement the value in register
.Sy SP
by 1.
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss DI
Disable Interrupts by clearing the
.Sy IME
flag.
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss EI
Enable Interrupts by setting the
.Sy IME
flag.
.Pp
The flag is only set
.Em after
the instruction following
.Sy EI .
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss HALT
Enter CPU low-power consumption mode until an interrupt occurs.
.Pp
The exact behavior of this instruction depends on the state of the
.Sy IME
flag, and whether interrupts are pending (i.e. whether
.Ql [IE] & [IF]
is non-zero):
.Bl -tag -width Ds -offset indent
.It If the Sy IME No flag is set:
The CPU enters low-power mode until
.Em after
an interrupt is about to be serviced.
The handler is executed normally, and the CPU resumes execution after the
.Ic HALT
when that returns.
.It If the Sy IME No flag is not set, and no interrupts are pending:
As soon as an interrupt becomes pending, the CPU resumes execution.
This is like the above, except that the handler is
.Em not
called.
.It If the Sy IME No flag is not set, and some interrupt is pending:
The CPU continues execution after the
.Ic HALT ,
but the byte after it is read twice in a row
.Po
.Sy PC
is not incremented, due to a hardware bug
.Pc .
.El
.Pp
Cycles: -
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss INC r8
Increment the value in register
.Ar r8
by 1.
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
Set if overflow from bit 3.
.El
.Ss INC [HL]
Increment the byte pointed to by
.Sy HL
by 1.
.Pp
Cycles: 3
.Pp
Bytes: 1
.Pp
Flags: See
.Sx INC r8
.Ss INC r16
Increment the value in register
.Ar r16
by 1.
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss INC SP
Increment the value in register
.Sy SP
by 1.
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss JP n16
Jump to address
.Ar n16 ;
effectively, copy
.Ar n16
into
.Sy PC .
.Pp
Cycles: 4
.Pp
Bytes: 3
.Pp
Flags: None affected.
.Ss JP cc,n16
Jump to address
.Ar n16
if condition
.Ar cc
is met.
.Pp
Cycles: 4 taken / 3 untaken
.Pp
Bytes: 3
.Pp
Flags: None affected.
.Ss JP HL
Jump to address in
.Sy HL ;
effectively, copy
the value in register
.Sy HL
into
.Sy PC .
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss JR n16
Relative Jump to address
.Ar n16 .
.Pp
The address is encoded as a signed 8-bit offset from the address immediately following the
.Ic JR
instruction, so the target address
.Ar n16
must be between
.Sy -128
and
.Sy 127
bytes away.
For example:
.Bd -literal -offset indent
    JR Label  ; no-op; encoded offset of 0
Label:
    JR Label  ; infinite loop; encoded offset of -2
.Ed
.Pp
Cycles: 3
.Pp
Bytes: 2
.Pp
Flags: None affected.
.Ss JR cc,n16
Relative Jump to address
.Ar n16
if condition
.Ar cc
is met.
.Pp
Cycles: 3 taken / 2 untaken
.Pp
Bytes: 2
.Pp
Flags: None affected.
.Ss LD r8,r8
Copy (aka Load) the value in register on the right into the register on the left.
.Pp
Storing a register into itself is a no-op; however, some Game Boy emulators interpret
.Sy LD B,B
as a breakpoint, or
.Sy LD D,D
as a debug message
.Po such as
.Lk https://bgb.bircd.org/manual.html#expressions BGB
.Pc .
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss LD r8,n8
Copy the value
.Ar n8
into register
.Ar r8 .
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags: None affected.
.Ss LD r16,n16
Copy the value
.Ar n16
into register
.Ar r16 .
.Pp
Cycles: 3
.Pp
Bytes: 3
.Pp
Flags: None affected.
.Ss LD [HL],r8
Copy the value in register
.Ar r8
into the byte pointed to by
.Sy HL .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss LD [HL],n8
Copy the value
.Ar n8
into the byte pointed to by
.Sy HL .
.Pp
Cycles: 3
.Pp
Bytes: 2
.Pp
Flags: None affected.
.Ss LD r8,[HL]
Copy the value pointed to by
.Sy HL
into register
.Ar r8 .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss LD [r16],A
Copy the value in register
.Sy A
into the byte pointed to by
.Ar r16 .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss LD [n16],A
Copy the value in register
.Sy A
into the byte at address
.Ar n16 .
.Pp
Cycles: 4
.Pp
Bytes: 3
.Pp
Flags: None affected.
.Ss LDH [n16],A
Copy the value in register
.Sy A
into the byte at address
.Ar n16 ,
provided the address is between
.Ad $FF00
and
.Ad $FFFF .
.Pp
Cycles: 3
.Pp
Bytes: 2
.Pp
Flags: None affected.
.Ss LDH [C],A
Copy the value in register
.Sy A
into the byte at address
.Ad $FF00+C .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Pp
This is sometimes written as
.Ql LD [$FF00+C],A .
.Ss LD A,[r16]
Copy the byte pointed to by
.Ar r16
into register
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss LD A,[n16]
Copy the byte at address
.Ar n16
into register
.Sy A .
.Pp
Cycles: 4
.Pp
Bytes: 3
.Pp
Flags: None affected.
.Ss LDH A,[n16]
Copy the byte at address
.Ar n16
into register
.Sy A ,
provided the address is between
.Ad $FF00
and
.Ad $FFFF .
.Pp
Cycles: 3
.Pp
Bytes: 2
.Pp
Flags: None affected.
.Ss LDH A,[C]
Copy the byte at address
.Ad $FF00+C
into register
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Pp
This is sometimes written as
.Ql LD A,[$FF00+C] .
.Ss LD [HLI],A
Copy the value in register
.Sy A
into the byte pointed by
.Sy HL
and increment
.Sy HL
afterwards.
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Pp
This is sometimes written as
.Ql LD [HL+],A ,
or
.Ql LDI [HL],A .
.Ss LD [HLD],A
Copy the value in register
.Sy A
into the byte pointed by
.Sy HL
and decrement
.Sy HL
afterwards.
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Pp
This is sometimes written as
.Ql LD [HL-],A ,
or
.Ql LDD [HL],A .
.Ss LD A,[HLD]
Copy the byte pointed to by
.Sy HL
into register
.Sy A ,
and decrement
.Sy HL
afterwards.
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Pp
This is sometimes written as
.Ql LD A,[HL-] ,
or
.Ql LDD A,[HL] .
.Ss LD A,[HLI]
Copy the byte pointed to by
.Sy HL
into register
.Sy A ,
and increment
.Sy HL
afterwards.
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Pp
This is sometimes written as
.Ql LD A,[HL+] ,
or
.Ql LDI A,[HL] .
.Ss LD SP,n16
Copy the value
.Ar n16
into register
.Sy SP .
.Pp
Cycles: 3
.Pp
Bytes: 3
.Pp
Flags: None affected.
.Ss LD [n16],SP
Copy
.Sy SP
&
.Ad $FF
at address
.Ar n16
and
.Sy SP
>> 8
at address
.Ar n16
+ 1.
.Pp
Cycles: 5
.Pp
Bytes: 3
.Pp
Flags: None affected.
.Ss LD HL,SP+e8
Add the signed value
.Ar e8
to
.Sy SP
and copy the result in
.Sy HL .
.Pp
Cycles: 3
.Pp
Bytes: 2
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
0
.It Sy N
0
.It Sy H
Set if overflow from bit 3.
.It Sy C
Set if overflow from bit 7.
.El
.Ss LD SP,HL
Copy register
.Sy HL
into register
.Sy SP .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss NOP
No OPeration.
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss OR A,r8
Set
.Sy A
to the bitwise OR between the value in
.Ar r8
and
.Sy A .
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
0
.It Sy C
0
.El
.Ss OR A,[HL]
Set
.Sy A
to the bitwise OR between the byte pointed to by
.Sy HL
and
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: See
.Sx OR A,r8
.Ss OR A,n8
Set
.Sy A
to the bitwise OR between the value
.Ar n8
and
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags: See
.Sx OR A,r8
.Ss POP AF
Pop register
.Sy AF
from the stack.
This is roughly equivalent to the following
.Em imaginary
instructions:
.Bd -literal -offset indent
    LD F, [SP]  ; See below for individual flags
    INC SP
    LD A, [SP]
    INC SP
.Ed
.Pp
Cycles: 3
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set from bit 7 of the popped low byte.
.It Sy N
Set from bit 6 of the popped low byte.
.It Sy H
Set from bit 5 of the popped low byte.
.It Sy C
Set from bit 4 of the popped low byte.
.El
.Ss POP r16
Pop register
.Ar r16
from the stack.
This is roughly equivalent to the following
.Em imaginary
instructions:
.Bd -literal -offset indent
    LD LOW(r16), [SP]   ; C, E or L
    INC SP
    LD HIGH(r16), [SP]  ; B, D or H
    INC SP
.Ed
.Pp
Cycles: 3
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss PUSH AF
Push register
.Sy AF
into the stack.
This is roughly equivalent to the following
.Em imaginary
instructions:
.Bd -literal -offset indent
    DEC SP
    LD [SP], A
    DEC SP
    LD [SP], F.Z << 7 | F.N << 6 | F.H << 5 | F.C << 4
.Ed
.Pp
Cycles: 4
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss PUSH r16
Push register
.Ar r16
into the stack.
This is roughly equivalent to the following
.Em imaginary
instructions:
.Bd -literal -offset indent
    DEC SP
    LD [SP], HIGH(r16)  ; B, D or H
    DEC SP
    LD [SP], LOW(r16)   ; C, E or L
.Ed
.Pp
Cycles: 4
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss RES u3,r8
Set bit
.Ar u3
in register
.Ar r8
to 0.
Bit 0 is the rightmost one, bit 7 the leftmost one.
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags: None affected.
.Ss RES u3,[HL]
Set bit
.Ar u3
in the byte pointed by
.Sy HL
to 0.
Bit 0 is the rightmost one, bit 7 the leftmost one.
.Pp
Cycles: 4
.Pp
Bytes: 2
.Pp
Flags: None affected.
.Ss RET
Return from subroutine.
This is basically a
.Sy POP PC
(if such an instruction existed).
See
.Sx POP r16
for an explanation of how
.Sy POP
works.
.Pp
Cycles: 4
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss RET cc
Return from subroutine if condition
.Ar cc
is met.
.Pp
Cycles: 5 taken / 2 untaken
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss RETI
Return from subroutine and enable interrupts.
This is basically equivalent to executing
.Sx EI
then
.Sx RET ,
meaning that
.Sy IME
is set right after this instruction.
.Pp
Cycles: 4
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss RL r8
Rotate bits in register
.Ar r8
left, through the carry flag.
.Bd -literal
  ┏━ Flags ━┓ ┏━━━━━━━ r8 ━━━━━━┓
┌─╂─   C   ←╂─╂─ b7 ← ... ← b0 ←╂─┐
│ ┗━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━┛ │
└─────────────────────────────────┘
.Ed
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
0
.It Sy C
Set according to result.
.El
.Ss RL [HL]
Rotate the byte pointed to by
.Sy HL
left, through the carry flag.
.Bd -literal
  ┏━ Flags ━┓ ┏━━━━━━ [HL] ━━━━━┓
┌─╂─   C   ←╂─╂─ b7 ← ... ← b0 ←╂─┐
│ ┗━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━┛ │
└─────────────────────────────────┘
.Ed
.Pp
Cycles: 4
.Pp
Bytes: 2
.Pp
Flags: See
.Sx RL r8
.Ss RLA
Rotate register
.Sy A
left, through the carry flag.
.Bd -literal
  ┏━ Flags ━┓ ┏━━━━━━━ A ━━━━━━━┓
┌─╂─   C   ←╂─╂─ b7 ← ... ← b0 ←╂─┐
│ ┗━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━┛ │
└─────────────────────────────────┘
.Ed
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
0
.It Sy N
0
.It Sy H
0
.It Sy C
Set according to result.
.El
.Ss RLC r8
Rotate register
.Ar r8
left.
.Bd -literal
┏━ Flags ━┓   ┏━━━━━━━ r8 ━━━━━━┓
┃    C   ←╂─┬─╂─ b7 ← ... ← b0 ←╂─┐
┗━━━━━━━━━┛ │ ┗━━━━━━━━━━━━━━━━━┛ │
            └─────────────────────┘
.Ed
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
0
.It Sy C
Set according to result.
.El
.Ss RLC [HL]
Rotate the byte pointed to by
.Sy HL
left.
.Bd -literal
┏━ Flags ━┓   ┏━━━━━━ [HL] ━━━━━┓
┃    C   ←╂─┬─╂─ b7 ← ... ← b0 ←╂─┐
┗━━━━━━━━━┛ │ ┗━━━━━━━━━━━━━━━━━┛ │
            └─────────────────────┘
.Ed
.Pp
Cycles: 4
.Pp
Bytes: 2
.Pp
Flags: See
.Sx RLC r8
.Ss RLCA
Rotate register
.Sy A
left.
.Bd -literal
┏━ Flags ━┓   ┏━━━━━━━ A ━━━━━━━┓
┃    C   ←╂─┬─╂─ b7 ← ... ← b0 ←╂─┐
┗━━━━━━━━━┛ │ ┗━━━━━━━━━━━━━━━━━┛ │
            └─────────────────────┘
.Ed
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
0
.It Sy N
0
.It Sy H
0
.It Sy C
Set according to result.
.El
.Ss RR r8
Rotate register
.Ar r8
right, through the carry flag.
.Bd -literal
  ┏━━━━━━━ r8 ━━━━━━┓ ┏━ Flags ━┓
┌─╂→ b7 → ... → b0 ─╂─╂→   C   ─╂─┐
│ ┗━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛ │
└─────────────────────────────────┘
.Ed
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
0
.It Sy C
Set according to result.
.El
.Ss RR [HL]
Rotate the byte pointed to by
.Sy HL
right, through the carry flag.
.Bd -literal
  ┏━━━━━━ [HL] ━━━━━┓ ┏━ Flags ━┓
┌─╂→ b7 → ... → b0 ─╂─╂→   C   ─╂─┐
│ ┗━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛ │
└─────────────────────────────────┘
.Ed
.Pp
Cycles: 4
.Pp
Bytes: 2
.Pp
Flags: See
.Sx RR r8
.Ss RRA
Rotate register
.Sy A
right, through the carry flag.
.Bd -literal
  ┏━━━━━━━ A ━━━━━━━┓ ┏━ Flags ━┓
┌─╂→ b7 → ... → b0 ─╂─╂→   C   ─╂─┐
│ ┗━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛ │
└─────────────────────────────────┘
.Ed
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
0
.It Sy N
0
.It Sy H
0
.It Sy C
Set according to result.
.El
.Ss RRC r8
Rotate register
.Ar r8
right.
.Bd -literal
  ┏━━━━━━━ r8 ━━━━━━┓   ┏━ Flags ━┓
┌─╂→ b7 → ... → b0 ─╂─┬─╂→   C    ┃
│ ┗━━━━━━━━━━━━━━━━━┛ │ ┗━━━━━━━━━┛
└─────────────────────┘
.Ed
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
0
.It Sy C
Set according to result.
.El
.Ss RRC [HL]
Rotate the byte pointed to by
.Sy HL
right.
.Bd -literal
  ┏━━━━━━ [HL] ━━━━━┓   ┏━ Flags ━┓
┌─╂→ b7 → ... → b0 ─╂─┬─╂→   C    ┃
│ ┗━━━━━━━━━━━━━━━━━┛ │ ┗━━━━━━━━━┛
└─────────────────────┘
.Ed
.Pp
Cycles: 4
.Pp
Bytes: 2
.Pp
Flags: See
.Sx RRC r8
.Ss RRCA
Rotate register
.Sy A
right.
.Bd -literal
  ┏━━━━━━━ A ━━━━━━━┓   ┏━ Flags ━┓
┌─╂→ b7 → ... → b0 ─╂─┬─╂→   C    ┃
│ ┗━━━━━━━━━━━━━━━━━┛ │ ┗━━━━━━━━━┛
└─────────────────────┘
.Ed
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
0
.It Sy N
0
.It Sy H
0
.It Sy C
Set according to result.
.El
.Ss RST vec
Call address
.Ar vec .
This is a shorter and faster equivalent to
.Sx CALL
for suitable values of
.Ar vec .
.Pp
Cycles: 4
.Pp
Bytes: 1
.Pp
Flags: None affected.
.Ss SBC A,r8
Subtract the value in
.Ar r8
and the carry flag from
.Sy A .
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
1
.It Sy H
Set if borrow from bit 4.
.It Sy C
Set if borrow (i.e. if
.Po Ar r8
+ carry
.Pc >
.Sy A ) .
.El
.Ss SBC A,[HL]
Subtract the byte pointed to by
.Sy HL
and the carry flag from
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: See
.Sx SBC A,r8
.Ss SBC A,n8
Subtract the value
.Ar n8
and the carry flag from
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags: See
.Sx SBC A,r8
.Ss SCF
Set Carry Flag.
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy N
0
.It Sy H
0
.It Sy C
1
.El
.Ss SET u3,r8
Set bit
.Ar u3
in register
.Ar r8
to 1.
Bit 0 is the rightmost one, bit 7 the leftmost one.
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags: None affected.
.Ss SET u3,[HL]
Set bit
.Ar u3
in the byte pointed by
.Sy HL
to 1.
Bit 0 is the rightmost one, bit 7 the leftmost one.
.Pp
Cycles: 4
.Pp
Bytes: 2
.Pp
Flags: None affected.
.Ss SLA r8
Shift Left Arithmetically register
.Ar r8 .
.Bd -literal
┏━ Flags ━┓ ┏━━━━━━━ r8 ━━━━━━┓
┃    C   ←╂─╂─ b7 ← ... ← b0 ←╂─ 0
┗━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━┛
.Ed
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
0
.It Sy C
Set according to result.
.El
.Ss SLA [HL]
Shift Left Arithmetically the byte pointed to by
.Sy HL .
.Bd -literal
┏━ Flags ━┓ ┏━━━━━━ [HL] ━━━━━┓
┃    C   ←╂─╂─ b7 ← ... ← b0 ←╂─ 0
┗━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━┛
.Ed
.Pp
Cycles: 4
.Pp
Bytes: 2
.Pp
Flags: See
.Sx SLA r8
.Ss SRA r8
Shift Right Arithmetically register
.Ar r8
.Pq bit 7 of Ar r8 No is unchanged .
.Bd -literal
┏━━━━━━ r8 ━━━━━━┓ ┏━ Flags ━┓
┃ b7 → ... → b0 ─╂─╂→   C    ┃
┗━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛
.Ed
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
0
.It Sy C
Set according to result.
.El
.Ss SRA [HL]
Shift Right Arithmetically the byte pointed to by
.Sy HL
.Pq bit 7 of the byte pointed to by Sy HL No is unchanged .
.Bd -literal
┏━━━━━ [HL] ━━━━━┓ ┏━ Flags ━┓
┃ b7 → ... → b0 ─╂─╂→   C    ┃
┗━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛
.Ed
.Pp
Cycles: 4
.Pp
Bytes: 2
.Pp
Flags: See
.Sx SRA r8
.Ss SRL r8
Shift Right Logically register
.Ar r8 .
.Bd -literal
   ┏━━━━━━━ r8 ━━━━━━┓ ┏━ Flags ━┓
0 ─╂→ b7 → ... → b0 ─╂─╂→   C    ┃
   ┗━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛
.Ed
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
0
.It Sy C
Set according to result.
.El
.Ss SRL [HL]
Shift Right Logically the byte pointed to by
.Sy HL .
.Bd -literal
   ┏━━━━━━ [HL] ━━━━━┓ ┏━ Flags ━┓
0 ─╂→ b7 → ... → b0 ─╂─╂→   C    ┃
   ┗━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛
.Ed
.Pp
Cycles: 4
.Pp
Bytes: 2
.Pp
Flags: See
.Sx SRL r8
.Ss STOP
Enter CPU very low power mode.
Also used to switch between GBC double speed and normal speed CPU modes.
.Pp
The exact behavior of this instruction is fragile and may interpret its second byte as a separate instruction
.Po see
.Lk https://gbdev.io/pandocs/Reducing_Power_Consumption.html#using-the-stop-instruction the Pan Docs
.Pc ,
which is why
.Xr rgbasm 1
allows explicitly specifying the second byte
.Pq Sy STOP Ar n8
to override the default of
.Ad $00
.Po a
.Sy NOP
instruction
.Pc .
.Pp
Cycles: -
.Pp
Bytes: 2
.Pp
Flags: None affected.
.Ss SUB A,r8
Subtract the value in
.Ar r8
from
.Sy A .
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
1
.It Sy H
Set if borrow from bit 4.
.It Sy C
Set if borrow (i.e. if
.Ar r8
>
.Sy A ) .
.El
.Ss SUB A,[HL]
Subtract the byte pointed to by
.Sy HL
from
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: See
.Sx SUB A,r8
.Ss SUB A,n8
Subtract the value
.Ar n8
from
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags: See
.Sx SUB A,r8
.Ss SWAP r8
Swap the upper 4 bits in register
.Ar r8
and the lower 4 ones.
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
0
.It Sy C
0
.El
.Ss SWAP [HL]
Swap the upper 4 bits in the byte pointed by
.Sy HL
and the lower 4 ones.
.Pp
Cycles: 4
.Pp
Bytes: 2
.Pp
Flags: See
.Sx SWAP r8
.Ss XOR A,r8
Set
.Sy A
to the bitwise XOR between the value in
.Ar r8
and
.Sy A .
.Pp
Cycles: 1
.Pp
Bytes: 1
.Pp
Flags:
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
0
.It Sy H
0
.It Sy C
0
.El
.Ss XOR A,[HL]
Set
.Sy A
to the bitwise XOR between the byte pointed to by
.Sy HL
and
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 1
.Pp
Flags: See
.Sx XOR A,r8
.Ss XOR A,n8
Set
.Sy A
to the bitwise XOR between the value
.Ar n8
and
.Sy A .
.Pp
Cycles: 2
.Pp
Bytes: 2
.Pp
Flags: See
.Sx XOR A,r8
.Sh SEE ALSO
.Xr rgbasm 1 ,
.Xr rgblink 1 ,
.Xr rgbfix 1 ,
.Xr rgbgfx 1 ,
.Xr rgbasm-old 5 ,
.Xr rgbds 7
.Sh HISTORY
.Xr rgbasm 1
was originally written by
.An Carsten S\(/orensen
as part of the ASMotor package, and was later repackaged in RGBDS by
.An Justin Lloyd .
It is now maintained by a number of contributors at
.Lk https://github.com/gbdev/rgbds .