gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-22 11:12:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve the instruction documentation (#1561)

Browse Source
This commit is contained in:
Sylvie
2024-12-02 15:41:57 -05:00
committed by GitHub
parent d5f39c8dce
commit 6982c8a116
1 changed files with 184 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

292
man/gbz80.7
View File

@@ -9,7 +9,7 @@
.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 dual speed mode) needed to complete them.
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
@@ -43,23 +43,36 @@ Any of the 8-bit registers
Any of the general-purpose 16-bit registers
.Pq Sy BC , DE , HL .
.It Ar n8
8-bit integer constant.
8-bit integer constant
.Po signed or unsigned,
.Sy -128
to
.Sy 255
.Pc .
.It Ar n16
16-bit integer constant.
16-bit integer constant
.Po signed or unsigned,
.Sy -32768
to
.Sy 65535
.Pc .
.It Ar e8
8-bit offset
8-bit signed offset
.Po Sy -128
to
.Sy 127
.Pc .
.It Ar u3
3-bit unsigned integer constant
3-bit unsigned bit index
.Po Sy 0
to
.Sy 7
.Sy 7 ,
with
.Sy 0
as the least significant bit
.Pc .
.It Ar cc
Condition codes:
A condition code:
.Bl -tag -width Ds -compact
.It Sy Z
Execute if Z is set.
@@ -71,9 +84,9 @@ Execute if C is set.
Execute if C is not set.
.El
.It Ar vec
One of the
An
.Sy RST
vectors
vector
.Po Ad 0x00 , 0x08 , 0x10 , 0x18 , 0x20 , 0x28 , 0x30 ,
and
.Ad 0x38 Pc .
@@ -363,7 +376,9 @@ Set if overflow from bit 3.
Set if overflow from bit 7.
.El
.Ss AND A,r8
Bitwise AND between the value in
Set
.Sy A
to the bitwise AND between the value in
.Ar r8
and
.Sy A .
@@ -384,7 +399,9 @@ Set if result is 0.
0
.El
.Ss AND A,[HL]
Bitwise AND between the byte pointed to by
Set
.Sy A
to the bitwise AND between the byte pointed to by
.Sy HL
and
.Sy A .
@@ -396,7 +413,9 @@ Bytes: 1
Flags: See
.Sx AND A,r8
.Ss AND A,n8
Bitwise AND between the value in
Set
.Sy A
to the bitwise AND between the value
.Ar n8
and
.Sy A .
@@ -443,6 +462,7 @@ Flags: See
.Ss CALL n16
Call address
.Ar n16 .
.Pp
This pushes the address of the instruction after the
.Sy CALL
on the stack, such that
@@ -484,12 +504,16 @@ Flags:
Inverted.
.El
.Ss CP A,r8
Subtract the value in
ComPare the value in
.Sy A
with the value in
.Ar r8 .
.Pp
This subtracts the value in
.Ar r8
from
.Sy A
and set flags accordingly, but don't store the result.
This is useful for ComParing values.
and sets flags accordingly, but discards the result.
.Pp
Cycles: 1
.Pp
@@ -510,11 +534,16 @@ Set if borrow (i.e. if
.Sy A ) .
.El
.Ss CP A,[HL]
Subtract the byte pointed to by
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 set flags accordingly, but don't store the result.
and sets flags accordingly, but discards the result.
.Pp
Cycles: 2
.Pp
@@ -523,11 +552,16 @@ Bytes: 1
Flags: See
.Sx CP A,r8
.Ss CP A,n8
Subtract the value
ComPare the value in
.Sy A
with the value
.Ar n8 .
.Pp
This subtracts the value
.Ar n8
from
.Sy A
and set flags accordingly, but don't store the result.
and sets flags accordingly, but discards the result.
.Pp
Cycles: 2
.Pp
@@ -540,7 +574,8 @@ ComPLement accumulator
.Po Sy A
=
.Sy ~A
.Pc .
.Pc ;
also called bitwise NOT.
.Pp
Cycles: 1
.Pp
@@ -560,7 +595,8 @@ 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 is as follows:
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
@@ -629,7 +665,7 @@ Set if result is 0.
Set or reset depending on the operation.
.El
.Ss DEC r8
Decrement value in register
Decrement the value in register
.Ar r8
by 1.
.Pp
@@ -658,7 +694,7 @@ Bytes: 1
Flags: See
.Sx DEC r8
.Ss DEC r16
Decrement value in register
Decrement the value in register
.Ar r16
by 1.
.Pp
@@ -668,7 +704,7 @@ Bytes: 1
.Pp
Flags: None affected.
.Ss DEC SP
Decrement value in register
Decrement the value in register
.Sy SP
by 1.
.Pp
@@ -691,6 +727,7 @@ Flags: None affected.
Enable Interrupts by setting the
.Sy IME
flag.
.Pp
The flag is only set
.Em after
the instruction following
@@ -703,28 +740,26 @@ Bytes: 1
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.
.Bl -tag -width Ds
.It Sy IME No set
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 Sy IME No not set
The behavior depends on whether an interrupt is pending (i.e.\&
.Ql [IE] & [IF]
is non-zero).
.Bl -tag -width Ds
.It None pending
.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 Some pending
.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
@@ -733,7 +768,6 @@ but the byte after it is read twice in a row
is not incremented, due to a hardware bug
.Pc .
.El
.El
.Pp
Cycles: -
.Pp
@@ -741,7 +775,7 @@ Bytes: 1
.Pp
Flags: None affected.
.Ss INC r8
Increment value in register
Increment the value in register
.Ar r8
by 1.
.Pp
@@ -770,7 +804,7 @@ Bytes: 1
Flags: See
.Sx INC r8
.Ss INC r16
Increment value in register
Increment the value in register
.Ar r16
by 1.
.Pp
@@ -780,7 +814,7 @@ Bytes: 1
.Pp
Flags: None affected.
.Ss INC SP
Increment value in register
Increment the value in register
.Sy SP
by 1.
.Pp
@@ -792,7 +826,7 @@ Flags: None affected.
.Ss JP n16
Jump to address
.Ar n16 ;
effectively, store
effectively, copy
.Ar n16
into
.Sy PC .
@@ -817,10 +851,11 @@ Flags: None affected.
.Ss JP HL
Jump to address in
.Sy HL ;
effectively, load
.Sy PC
with value in register
.Sy HL .
effectively, copy
the value in register
.Sy HL
into
.Sy PC .
.Pp
Cycles: 1
.Pp
@@ -830,6 +865,7 @@ 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
@@ -864,7 +900,16 @@ Bytes: 2
.Pp
Flags: None affected.
.Ss LD r8,r8
Load (copy) value in register on the right into register on the left.
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
@@ -872,7 +917,7 @@ Bytes: 1
.Pp
Flags: None affected.
.Ss LD r8,n8
Load value
Copy the value
.Ar n8
into register
.Ar r8 .
@@ -883,7 +928,7 @@ Bytes: 2
.Pp
Flags: None affected.
.Ss LD r16,n16
Load value
Copy the value
.Ar n16
into register
.Ar r16 .
@@ -894,9 +939,9 @@ Bytes: 3
.Pp
Flags: None affected.
.Ss LD [HL],r8
Store value in register
Copy the value in register
.Ar r8
into the byte pointed to by register
into the byte pointed to by
.Sy HL .
.Pp
Cycles: 2
@@ -905,9 +950,9 @@ Bytes: 1
.Pp
Flags: None affected.
.Ss LD [HL],n8
Store value
Copy the value
.Ar n8
into the byte pointed to by register
into the byte pointed to by
.Sy HL .
.Pp
Cycles: 3
@@ -916,10 +961,10 @@ Bytes: 2
.Pp
Flags: None affected.
.Ss LD r8,[HL]
Load value into register
.Ar r8
from the byte pointed to by register
.Sy HL .
Copy the value pointed to by
.Sy HL
into register
.Ar r8 .
.Pp
Cycles: 2
.Pp
@@ -927,9 +972,9 @@ Bytes: 1
.Pp
Flags: None affected.
.Ss LD [r16],A
Store value in register
Copy the value in register
.Sy A
into the byte pointed to by register
into the byte pointed to by
.Ar r16 .
.Pp
Cycles: 2
@@ -938,7 +983,7 @@ Bytes: 1
.Pp
Flags: None affected.
.Ss LD [n16],A
Store value in register
Copy the value in register
.Sy A
into the byte at address
.Ar n16 .
@@ -949,7 +994,7 @@ Bytes: 3
.Pp
Flags: None affected.
.Ss LDH [n16],A
Store value in register
Copy the value in register
.Sy A
into the byte at address
.Ar n16 ,
@@ -969,7 +1014,7 @@ This is sometimes written as
or
.Ql LD [$FF00+n8],A .
.Ss LDH [C],A
Store value in register
Copy the value in register
.Sy A
into the byte at address
.Ad $FF00+C .
@@ -985,10 +1030,10 @@ This is sometimes written as
or
.Ql LD [$FF00+C],A .
.Ss LD A,[r16]
Load value in register
.Sy A
from the byte pointed to by register
.Ar r16 .
Copy the byte pointed to by
.Ar r16
into register
.Sy A .
.Pp
Cycles: 2
.Pp
@@ -996,10 +1041,10 @@ Bytes: 1
.Pp
Flags: None affected.
.Ss LD A,[n16]
Load value in register
.Sy A
from the byte at address
.Ar n16 .
Copy the byte at address
.Ar n16
into register
.Sy A .
.Pp
Cycles: 4
.Pp
@@ -1007,10 +1052,10 @@ Bytes: 3
.Pp
Flags: None affected.
.Ss LDH A,[n16]
Load value in register
.Sy A
from the byte at address
.Ar n16 ,
Copy the byte at address
.Ar n16
into register
.Sy A ,
provided the address is between
.Ad $FF00
and
@@ -1027,10 +1072,10 @@ This is sometimes written as
or
.Ql LD A,[$FF00+n8] .
.Ss LDH A,[C]
Load value in register
.Sy A
from the byte at address
.Ad $FF00+c .
Copy the byte at address
.Ad $FF00+c
into register
.Sy A .
.Pp
Cycles: 2
.Pp
@@ -1043,7 +1088,7 @@ This is sometimes written as
or
.Ql LD A,[$FF00+C] .
.Ss LD [HLI],A
Store value in register
Copy the value in register
.Sy A
into the byte pointed by
.Sy HL
@@ -1062,7 +1107,7 @@ This is sometimes written as
or
.Ql LDI [HL],A .
.Ss LD [HLD],A
Store value in register
Copy the value in register
.Sy A
into the byte pointed by
.Sy HL
@@ -1081,10 +1126,10 @@ This is sometimes written as
or
.Ql LDD [HL],A .
.Ss LD A,[HLD]
Load value into register
.Sy A
from the byte pointed by
Copy the byte pointed to by
.Sy HL
into register
.Sy A ,
and decrement
.Sy HL
afterwards.
@@ -1100,10 +1145,10 @@ This is sometimes written as
or
.Ql LDD A,[HL] .
.Ss LD A,[HLI]
Load value into register
.Sy A
from the byte pointed by
Copy the byte pointed to by
.Sy HL
into register
.Sy A ,
and increment
.Sy HL
afterwards.
@@ -1119,7 +1164,7 @@ This is sometimes written as
or
.Ql LDI A,[HL] .
.Ss LD SP,n16
Load value
Copy the value
.Ar n16
into register
.Sy SP .
@@ -1130,7 +1175,7 @@ Bytes: 3
.Pp
Flags: None affected.
.Ss LD [n16],SP
Store
Copy
.Sy SP
&
.Ad $FF
@@ -1153,7 +1198,7 @@ Add the signed value
.Ar e8
to
.Sy SP
and store the result in
and copy the result in
.Sy HL .
.Pp
Cycles: 3
@@ -1172,7 +1217,7 @@ Set if overflow from bit 3.
Set if overflow from bit 7.
.El
.Ss LD SP,HL
Load register
Copy register
.Sy HL
into register
.Sy SP .
@@ -1191,9 +1236,9 @@ Bytes: 1
.Pp
Flags: None affected.
.Ss OR A,r8
Store into
Set
.Sy A
the bitwise OR of the value in
to the bitwise OR between the value in
.Ar r8
and
.Sy A .
@@ -1214,9 +1259,9 @@ Set if result is 0.
0
.El
.Ss OR A,[HL]
Store into
Set
.Sy A
the bitwise OR of the byte pointed to by
to the bitwise OR between the byte pointed to by
.Sy HL
and
.Sy A .
@@ -1228,9 +1273,9 @@ Bytes: 1
Flags: See
.Sx OR A,r8
.Ss OR A,n8
Store into
Set
.Sy A
the bitwise OR of
to the bitwise OR between the value
.Ar n8
and
.Sy A .
@@ -1249,10 +1294,10 @@ 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
LD F, [SP] ; See below for individual flags
INC SP
LD A, [SP]
INC SP
.Ed
.Pp
Cycles: 3
@@ -1278,10 +1323,10 @@ 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
LD LOW(r16), [SP] ; C, E or L
INC SP
LD HIGH(r16), [SP] ; B, D or H
INC SP
.Ed
.Pp
Cycles: 3
@@ -1297,10 +1342,10 @@ This is roughly equivalent to the following
.Em imaginary
instructions:
.Bd -literal -offset indent
dec sp
ld [sp], a
dec sp
ld [sp], flag_Z << 7 | flag_N << 6 | flag_H << 5 | flag_C << 4
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
@@ -1316,10 +1361,10 @@ 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
DEC SP
LD [SP], HIGH(r16) ; B, D or H
DEC SP
LD [SP], LOW(r16) ; C, E or L
.Ed
.Pp
Cycles: 4
@@ -1895,7 +1940,22 @@ Flags: See
.Sx SRL r8
.Ss STOP
Enter CPU very low power mode.
Also used to switch between double and normal speed CPU modes in GBC.
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
@@ -1982,7 +2042,9 @@ Bytes: 2
Flags: See
.Sx SWAP r8
.Ss XOR A,r8
Bitwise XOR between the value in
Set
.Sy A
to the bitwise XOR between the value in
.Ar r8
and
.Sy A .
@@ -2003,7 +2065,9 @@ Set if result is 0.
0
.El
.Ss XOR A,[HL]
Bitwise XOR between the byte pointed to by
Set
.Sy A
to the bitwise XOR between the byte pointed to by
.Sy HL
and
.Sy A .
@@ -2015,7 +2079,9 @@ Bytes: 1
Flags: See
.Sx XOR A,r8
.Ss XOR A,n8
Bitwise XOR between the value in
Set
.Sy A
to the bitwise XOR between the value
.Ar n8
and
.Sy A .