diff --git a/docs/gbz80.7.html b/docs/gbz80.7.html index d1d77b28..830ee3f6 100644 --- a/docs/gbz80.7.html +++ b/docs/gbz80.7.html @@ -1,13 +1,14 @@ + - GBZ80(7) @@ -20,1691 +21,1442 @@
-

NAME

-gbz80 — CPU - opcode reference -

DESCRIPTION

-This is the list of opcodes supported by 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. -
-Note: All arithmetic/logic operations that use register - A as destination can omit the destination as it - is assumed it's register A. The following two - lines have the same effect: -
-
-
-OR A,B 
+

+

+gbz80 —
+
CPU opcode reference

+

+

+

+This is the list of opcodes supported by 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.
+
Note: All arithmetic/logic operations that use register
+    A as destination can omit the destination as it is assumed
+    it's register A. The following two lines have the same
+    effect:

+

+
+OR A,B
 OR B
 

 

-
LEGEND

+

+

+

 List of abbreviations used in this document.
 

-  
 

-  
 

-  
r8

-  
Any of the 8-bit registers (A,
-      B, C,
-      D, E,
-      H, L).

-  
 

-  
 

-  
r16

-  
Any of the general-purpose 16-bit registers
-      (BC, DE,
-      HL).

-  
 

-  
 

-  
n8

-  
8-bit integer constant.

-  
 

-  
 

-  
n16

-  
16-bit integer constant.

-  
 

-  
 

-  
e8

-  
8-bit offset
-      (-128 to
-      127).

-  
 

-  
 

-  
u3

-  
3-bit unsigned integer constant
-      (0 to 7).

-  
 

-  
 

-  
cc

-  
Condition codes:
+  
r8

+  
Any of the 8-bit registers (A, B,
+      C, D, E,
+      H, L).

+  
r16

+  
Any of the general-purpose 16-bit registers (BC,
+      DE, HL).

+  
n8

+  
8-bit integer constant.

+  
n16

+  
16-bit integer constant.

+  
e8

+  
8-bit offset (-128 to
+      127).

+  
u3

+  
3-bit unsigned integer constant (0 to
+      7).

+  
cc

+  
Condition codes:
     

-      
Z:

-      
Execute if Z is set.

-      
NZ:

-      
Execute if Z is not set.

-      
C:

-      
Execute if C is set.

-      
NC:

-      
Execute if C is not set.

+      
Z:

+      
Execute if Z is set.

+      
NZ:

+      
Execute if Z is not set.

+      
C:

+      
Execute if C is set.

+      
NC:

+      
Execute if C is not set.

     

   

-  
 

-  
 

-  
vec

-  
One of the RST vectors
-      (0x00, 0x08,
-      0x10, 0x18,
-      0x20, 0x28,
-      0x30 and
-    0x38).

+  
vec

+  
One of the RST vectors (0x00,
+      0x08, 0x10, 0x18,
+      0x20, 0x28, 0x30 and
+      0x38).

 

-
INSTRUCTION
+

+

+

-
8-bit
+

+

 

-  
ADC
-    A,r8

-  

-  
ADC
-    A,[HL]

-  

-  
ADC
-    A,n8

-  

-  
ADD
-    A,r8

-  

-  
ADD
-    A,[HL]

-  

-  
ADD
-    A,n8

-  

-  
AND
-    A,r8

-  

-  
AND
-    A,[HL]

-  

-  
AND
-    A,n8

-  

-  
CP A,r8

-  

-  
CP
-    A,[HL]

-  

-  
CP A,n8

-  

-  
DEC r8

-  

-  
DEC
-    [HL]

-  

-  
INC r8

-  

-  
INC
-    [HL]

-  

-  
OR A,r8

-  

-  
OR
-    A,[HL]

-  

-  
OR A,n8

-  

-  
SBC
-    A,r8

-  

-  
SBC
-    A,[HL]

-  

-  
SBC
-    A,n8

-  

-  
SUB
-    A,r8

-  

-  
SUB
-    A,[HL]

-  

-  
SUB
-    A,n8

-  

-  
XOR
-    A,r8

-  

-  
XOR
-    A,[HL]

-  

-  
XOR
-    A,n8

-  

+  
ADC A,r8

+  

+  
ADC A,[HL]

+  

+  
ADC A,n8

+  

+  
ADD A,r8

+  

+  
ADD A,[HL]

+  

+  
ADD A,n8

+  

+  
AND A,r8

+  

+  
AND A,[HL]

+  

+  
AND A,n8

+  

+  
CP A,r8

+  

+  
CP A,[HL]

+  

+  
CP A,n8

+  

+  
DEC r8

+  

+  
DEC [HL]

+  

+  
INC r8

+  

+  
INC [HL]

+  

+  
OR A,r8

+  

+  
OR A,[HL]

+  

+  
OR A,n8

+  

+  
SBC A,r8

+  

+  
SBC A,[HL]

+  

+  
SBC A,n8

+  

+  
SUB A,r8

+  

+  
SUB A,[HL]

+  

+  
SUB A,n8

+  

+  
XOR A,r8

+  

+  
XOR A,[HL]

+  

+  
XOR A,n8

+  

 

-
16-bit
+

+

+

 

-  
ADD
-    HL,r16

-  

-  
DEC r16

-  

-  
INC r16

-  

+  
ADD HL,r16

+  

+  
DEC r16

+  

+  
INC r16

+  

 

-
Bit
+

+

+

 

-  
BIT
-    u3,r8

-  

-  
BIT
-    u3,[HL]

-  

-  
RES
-    u3,r8

-  

-  
RES
-    u3,[HL]

-  

-  
SET
-    u3,r8

-  

-  
SET
-    u3,[HL]

-  

-  
SWAP r8

-  

-  
SWAP
-    [HL]

-  

+  
BIT u3,r8

+  

+  
BIT u3,[HL]

+  

+  
RES u3,r8

+  

+  
RES u3,[HL]

+  

+  
SET u3,r8

+  

+  
SET u3,[HL]

+  

+  
SWAP r8

+  

+  
SWAP [HL]

+  

 

-
Bit
+

+

+

 

-  
RL r8

-  

-  
RL [HL]

-  

-  
RLA

-  

-  
RLC r8

-  

-  
RLC
-    [HL]

-  

-  
RLCA

-  

-  
RR r8

-  

-  
RR [HL]

-  

-  
RRA

-  

-  
RRC r8

-  

-  
RRC
-    [HL]

-  

-  
RRCA

-  

-  
SLA r8

-  

-  
SLA
-    [HL]

-  

-  
SRA r8

-  

-  
SRA
-    [HL]

-  

-  
SRL r8

-  

-  
SRL
-    [HL]

-  

+  
RL r8

+  

+  
RL [HL]

+  

+  
RLA

+  

+  
RLC r8

+  

+  
RLC [HL]

+  

+  
RLCA

+  

+  
RR r8

+  

+  
RR [HL]

+  

+  
RRA

+  

+  
RRC r8

+  

+  
RRC [HL]

+  

+  
RRCA

+  

+  
SLA r8

+  

+  
SLA [HL]

+  

+  
SRA r8

+  

+  
SRA [HL]

+  

+  
SRL r8

+  

+  
SRL [HL]

+  

 

-
Load
+

+

+

 

-  
LD
-    r8,r8

-  

-  
LD
-    r8,n8

-  

-  
LD
-    r16,n16

-  

-  
LD
-    [HL],r8

-  

-  
LD
-    [HL],n8

-  

-  
LD
-    r8,[HL]

-  

-  
LD
-    [r16],A

-  

-  
LD
-    [n16],A

-  

-  
LD
-    [$FF00+n8],A

-  

-  
LD
-    [$FF00+C],A

-  

-  
LD
-    A,[r16]

-  

-  
LD
-    A,[n16]

-  

-  
LD
-    A,[$FF00+n8]

-  

-  
LD
-    A,[$FF00+C]

-  

-  
LD
-    [HL+],A

-  

-  
LD
-    [HL-],A

-  

-  
LD
-    A,[HL+]

-  

-  
LD
-    A,[HL-]

-  

+  
LD r8,r8

+  

+  
LD r8,n8

+  

+  
LD r16,n16

+  

+  
LD [HL],r8

+  

+  
LD [HL],n8

+  

+  
LD r8,[HL]

+  

+  
LD [r16],A

+  

+  
LD [n16],A

+  

+  
LD [$FF00+n8],A

+  

+  
LD [$FF00+C],A

+  

+  
LD A,[r16]

+  

+  
LD A,[n16]

+  

+  
LD A,[$FF00+n8]

+  

+  
LD A,[$FF00+C]

+  

+  
LD [HL+],A

+  

+  
LD [HL-],A

+  

+  
LD A,[HL+]

+  

+  
LD A,[HL-]

+  

 

-
Jumps
+

+

+

 

-  
CALL
-    n16

-  

-  
CALL
-    cc,n16

-  

-  
JP HL

-  

-  
JP n16

-  

-  
JP
-    cc,n16

-  

-  
JR e8

-  

-  
JR
-    cc,e8

-  

-  
RET cc

-  

-  
RET

-  

-  
RETI

-  

-  
RST vec

-  

+  
CALL n16

+  

+  
CALL cc,n16

+  

+  
JP HL

+  

+  
JP n16

+  

+  
JP cc,n16

+  

+  
JR e8

+  

+  
JR cc,e8

+  

+  
RET cc

+  

+  
RET

+  

+  
RETI

+  

+  
RST vec

+  

 

-
Stack
+

+

+

 

-  
ADD
-    HL,SP

-  

-  
ADD
-    SP,e8

-  

-  
DEC SP

-  

-  
INC SP

-  

-  
LD
-    SP,n16

-  

-  
LD
-    [n16],SP

-  

-  
LD
-    HL,SP+e8

-  

-  
LD
-    SP,HL

-  

-  
POP AF

-  

-  
POP r16

-  

-  
PUSH AF

-  

-  
PUSH
-    r16

-  

+  
ADD HL,SP

+  

+  
ADD SP,e8

+  

+  
DEC SP

+  

+  
INC SP

+  

+  
LD SP,n16

+  

+  
LD [n16],SP

+  

+  
LD HL,SP+e8

+  

+  
LD SP,HL

+  

+  
POP AF

+  

+  
POP r16

+  

+  
PUSH AF

+  

+  
PUSH r16

+  

 

-
Miscellaneous
+

+

+

 

-  
CCF

-  

-  
CPL

-  

-  
DAA

-  

-  
DI

-  

-  
EI

-  

-  
HALT

-  

-  
NOP

-  

-  
SCF

-  

-  
STOP

-  

+  
CCF

+  

+  
CPL

+  

+  
DAA

+  

+  
DI

+  

+  
EI

+  

+  
HALT

+  

+  
NOP

+  

+  
SCF

+  

+  
STOP

+  

 

-
INSTRUCTION
+

+

+

+

-
ADC
+

+

-Add the value in r8 plus the carry flag to
-  A.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Add the value in r8 plus the carry flag to
+  A.
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: Set if overflow from bit
-      3.
    • 
-  
  • C: Set if overflow from bit
-      7.
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: Set if overflow from bit 3.
    • 
+  
  • C: Set if overflow from bit 7.
    • 
 

-
ADC
+

+

+

-Add the value pointed by HL plus the carry flag to
-  A.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: See ADC A,r8
-
ADC
+Add the value pointed by HL plus the carry flag to
+  A.
+
Cycles: 2

+
Bytes: 1

+
Flags: See ADC A,r8

+

+

+

-Add the value n8 plus the carry flag to
-  A.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags: See ADC A,r8
-
ADD
+Add the value n8 plus the carry flag to
+  A.
+
Cycles: 2

+
Bytes: 2

+
Flags: See ADC A,r8

+

+

+

-Add the value in r8 to
-  A.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Add the value in r8 to A.
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: Set if overflow from bit
-      3.
    • 
-  
  • C: Set if overflow from bit
-      7.
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: Set if overflow from bit 3.
    • 
+  
  • C: Set if overflow from bit 7.
    • 
 

-
ADD
+

+

+

-Add the value pointed by HL to
-  A.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: See ADD A,r8
-
ADD
+Add the value pointed by HL to A.
+
Cycles: 2

+
Bytes: 1

+
Flags: See ADD A,r8

+

+

+

-Add the value n8 to
-  A.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags: See ADD A,r8
-
ADD
+Add the value n8 to A.
+
Cycles: 2

+
Bytes: 2

+
Flags: See ADD A,r8

+

+

+

-Add the value in r16 to
-  HL.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags:
+Add the value in r16 to HL.
+
Cycles: 2

+
Bytes: 1

+
Flags:

 
    
-  
  • N: 0
    • 
-  
  • H: Set if overflow from bit
-      11.
    • 
-  
  • C: Set if overflow from bit
-      15.
    • 
+  
  • N: 0
    • 
+  
  • H: Set if overflow from bit 11.
    • 
+  
  • C: Set if overflow from bit 15.
    • 
 

-
ADD
+

+

+

-Add the value in SP to
-  HL.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: See ADD HL,r16
-
ADD
+Add the value in SP to HL.
+
Cycles: 2

+
Bytes: 1

+
Flags: See ADD HL,r16

+

+

+

-Add the signed value e8 to
-  SP.
-

-Cycles: 4
-

-Bytes: 2
-

-Flags:
+Add the signed value e8 to SP.
+
Cycles: 4

+
Bytes: 2

+
Flags:

 
    
-  
  • Z: 0
    • 
-  
  • N: 0
    • 
-  
  • H: Set if overflow from bit
-      3.
    • 
-  
  • C: Set if overflow from bit
-      7.
    • 
+  
  • Z: 0
    • 
+  
  • N: 0
    • 
+  
  • H: Set if overflow from bit 3.
    • 
+  
  • C: Set if overflow from bit 7.
    • 
 

-
AND
+

+

+

-Bitwise AND between the value in r8 and
-  A.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Bitwise AND between the value in r8 and
+  A.
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: 1
    • 
-  
  • C: 0
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: 1
    • 
+  
  • C: 0
    • 
 

-
AND
+

+

+

-Bitwise AND between the value pointed by HL and
-  A.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: See AND A,r8
-
AND
+Bitwise AND between the value pointed by HL and
+  A.
+
Cycles: 2

+
Bytes: 1

+
Flags: See AND A,r8

+

+

+

-Bitwise AND between the value in n8 and
-  A.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags: See AND A,r8
-
BIT
+Bitwise AND between the value in n8 and
+  A.
+
Cycles: 2

+
Bytes: 2

+
Flags: See AND A,r8

+

+

+

-Test bit u3 in register
-  r8, set the zero flag if bit not set.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags:
+Test bit u3 in register r8, set the
+  zero flag if bit not set.
+
Cycles: 2

+
Bytes: 2

+
Flags:

 
    
-  
  • Z: Set if the selected bit
-      is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: 1
    • 
+  
  • Z: Set if the selected bit is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: 1
    • 
 

-
BIT
+

+

+

-Test bit u3 in the byte pointed by
-  HL, set the zero flag if bit not set.
-

-Cycles: 3
-

-Bytes: 2
-

-Flags: See BIT u3,r8
-
CALL
+Test bit u3 in the byte pointed by HL,
+  set the zero flag if bit not set.
+
Cycles: 3

+
Bytes: 2

+
Flags: See BIT u3,r8

+

+

+

-Call address n16.
-

-Cycles: 6
-

-Bytes: 3
-

-Flags: None affected.
-
CALL
+Call address n16.
+
Cycles: 6

+
Bytes: 3

+
Flags: None affected.

+

+

+

-Call address n16 if condition
-  cc is met.
-

-Cycles: 6/3
-

-Bytes: 3
-

-Flags: None affected.
-
CCF

+Call address n16 if condition cc is
+  met.
+
Cycles: 6/3

+
Bytes: 3

+
Flags: None affected.

+

+

+

 Complement Carry Flag.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: Complemented.
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: Complemented.
    • 
 

-
CP
+

+

+

-Subtract the value in r8 from
-  A and set flags accordingly, but don't store the
-  result.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Subtract the value in r8 from A and set
+  flags accordingly, but don't store the result.
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 1
    • 
-  
  • H: Set if no borrow from
-      bit 4.
    • 
-  
  • C: Set if no borrow (set if
-      r8 >
-    A).
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 1
    • 
+  
  • H: Set if no borrow from bit 4.
    • 
+  
  • C: Set if no borrow (set if r8
+      > A).
    • 
 

-
CP
+

+

+

-Subtract the value pointed by HL from
-  A and set flags accordingly, but don't store the
-  result.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: See CP A,r8
-
CP
+Subtract the value pointed by HL from A and
+  set flags accordingly, but don't store the result.
+
Cycles: 2

+
Bytes: 1

+
Flags: See CP A,r8

+

+

+

-Subtract the value n8 from
-  A and set flags accordingly, but don't store the
-  result.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags: See CP A,r8
-
CPL

-Complement accumulator (A =
-  ~A).
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Subtract the value n8 from A and set
+  flags accordingly, but don't store the result.
+
Cycles: 2

+
Bytes: 2

+
Flags: See CP A,r8

+

+

+

+Complement accumulator (A = ~A).
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • N: 1
    • 
-  
  • H: 1
    • 
+  
  • N: 1
    • 
+  
  • H: 1
    • 
 

-
DAA

+

+

+

 Decimal adjust register A to get a correct BCD representation after an
   arithmetic instruction.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • H: 0
    • 
-  
  • C: Set or reset depending
-      on the operation.
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • H: 0
    • 
+  
  • C: Set or reset depending on the operation.
    • 
 

-
DEC
-  r8

-Decrement value in register r8 by 1.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+

+

+

+Decrement value in register r8 by 1.
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 1
    • 
-  
  • H: Set if no borrow from
-      bit 4.
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 1
    • 
+  
  • H: Set if no borrow from bit 4.
    • 
 

-
DEC
+

+

+

-Decrement the value pointed by HL by 1.
-

-Cycles: 3
-

-Bytes: 1
-

-Flags: See DEC r8
-
DEC
+Decrement the value pointed by HL by 1.
+
Cycles: 3

+
Bytes: 1

+
Flags: See DEC r8

+

+

+

-Decrement value in register r16 by 1.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
DEC
-  SP

-Decrement value in register SP by 1.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
DI

+Decrement value in register r16 by 1.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

+Decrement value in register SP by 1.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

 Disable Interrupts.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags: None affected.
-
EI

+
Cycles: 1

+
Bytes: 1

+
Flags: None affected.

+

+

+

 Enable Interrupts.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags: None affected.
-
HALT

+
Cycles: 1

+
Bytes: 1

+
Flags: None affected.

+

+

+

 Enter CPU low power mode.
-

-Cycles: -
-

-Bytes: 1
-

-Flags: None affected.
-
INC
-  r8

-Increment value in register r8 by 1.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+
Cycles: -

+
Bytes: 1

+
Flags: None affected.

+

+

+

+Increment value in register r8 by 1.
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: Set if overflow from bit
-      3.
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: Set if overflow from bit 3.
    • 
 

-
INC
+

+

+

-Increment the value pointed by HL by 1.
-

-Cycles: 3
-

-Bytes: 1
-

-Flags: See INC r8
-
INC
+Increment the value pointed by HL by 1.
+
Cycles: 3

+
Bytes: 1

+
Flags: See INC r8

+

+

+

-Increment value in register r16 by 1.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
INC
-  SP

-Increment value in register SP by 1.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
JP
-  n16

-Absolute jump to address n16.
-

-Cycles: 4
-

-Bytes: 3
-

-Flags: None affected.
-
JP
+Increment value in register r16 by 1.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

+Increment value in register SP by 1.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

+Absolute jump to address n16.
+
Cycles: 4

+
Bytes: 3

+
Flags: None affected.

+

+

+

-Absolute jump to address n16 if condition
-  cc is met.
-

-Cycles: 4/3
-

-Bytes: 3
-

-Flags: None affected.
-
JP
-  HL

-Jump to address in HL, that is, load
-  PC with value in register
-  HL.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags: None affected.
-
JR
-  e8

-Relative jump by adding e8 to the current
-  address.
-

-Cycles: 3
-

-Bytes: 2
-

-Flags: None affected.
-
JR
+Absolute jump to address n16 if condition
+  cc is met.
+
Cycles: 4/3

+
Bytes: 3

+
Flags: None affected.

+

+

+

+Jump to address in HL, that is, load PC with
+  value in register HL.
+
Cycles: 1

+
Bytes: 1

+
Flags: None affected.

+

+

+

+Relative jump by adding e8 to the current address.
+
Cycles: 3

+
Bytes: 2

+
Flags: None affected.

+

+

+

-Relative jump by adding e8 to the current
-  address if condition cc is met.
-

-Cycles: 3/2
-

-Bytes: 2
-

-Flags: None affected.
-
LD
+Relative jump by adding e8 to the current address if
+  condition cc is met.
+
Cycles: 3/2

+
Bytes: 2

+
Flags: None affected.

+

+

+

 Store value in register on the right into register on the left.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags: None affected.
-
LD
+
Cycles: 1

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Load value n8 into register
-  r8.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags: None affected.
-
LD
+Load value n8 into register r8.
+
Cycles: 2

+
Bytes: 2

+
Flags: None affected.

+

+

+

-Load value n16 into register
-  r16.
-

-Cycles: 3
-

-Bytes: 3
-

-Flags: None affected.
-
LD
+Load value n16 into register r16.
+
Cycles: 3

+
Bytes: 3

+
Flags: None affected.

+

+

+

-Store value in register r8 into byte pointed by
-  register HL.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
LD
+Store value in register r8 into byte pointed by register
+  HL.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Store value n8 into byte pointed by register
-  HL.
-

-Cycles: 3
-

-Bytes: 2
-

-Flags: None affected.
-
LD
+Store value n8 into byte pointed by register
+  HL.
+
Cycles: 3

+
Bytes: 2

+
Flags: None affected.

+

+

+

-Load value into register r8 from byte pointed
-  by register HL.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
LD
+Load value into register r8 from byte pointed by register
+  HL.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Store value in register A into address pointed by
-  register r16.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
LD
+Store value in register A into address pointed by register
+  r16.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Store value in register A into address
-  n16.
-

-Cycles: 4
-

-Bytes: 3
-

-Flags: None affected.
-
LD
+Store value in register A into address
+  n16.
+
Cycles: 4

+
Bytes: 3

+
Flags: None affected.

+

+

+

-Store value in register A into high RAM or I/O
-  registers.
-

-The following synonym forces this encoding: LDH
-  [$FF00+n8],A
-

-Cycles: 3
-

-Bytes: 2
-

-Flags: None affected.
-
LD
+Store value in register A into high RAM or I/O registers.
+
The following synonym forces this encoding: LDH
+    [$FF00+n8],A

+
Cycles: 3

+
Bytes: 2

+
Flags: None affected.

+

+

+

-Store value in register A into high RAM or I/O
-  registers.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
LD
+Store value in register A into high RAM or I/O registers.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Load value in register A from address pointed by
-  register r16.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
LD
+Load value in register A from address pointed by register
+  r16.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Load value in register A from address
-  n16.
-

-Cycles: 4
-

-Bytes: 3
-

-Flags: None affected.
-
LD
+Load value in register A from address
+  n16.
+
Cycles: 4

+
Bytes: 3

+
Flags: None affected.

+

+

+

-Load value in register A from high RAM or I/O
-  registers.
-

-The following synonym forces this encoding: LDH
-  A,[$FF00+n8]
-

-Cycles: 3
-

-Bytes: 2
-

-Flags: None affected.
-
LD
+Load value in register A from high RAM or I/O registers.
+
The following synonym forces this encoding: LDH
+    A,[$FF00+n8]

+
Cycles: 3

+
Bytes: 2

+
Flags: None affected.

+

+

+

-Load value in register A from high RAM or I/O
-  registers.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
LD
+Load value in register A from high RAM or I/O registers.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Store value in register A into byte pointed by
-  HL and post-increment
-  HL.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
LD
+Store value in register A into byte pointed by
+  HL and post-increment HL.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Store value in register A into byte pointed by
-  HL and post-decrement
-  HL.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
LD
+Store value in register A into byte pointed by
+  HL and post-decrement HL.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Load value into register A from byte pointed by
-  HL and post-increment
-  HL.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
LD
+Load value into register A from byte pointed by
+  HL and post-increment HL.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Load value into register A from byte pointed by
-  HL and post-decrement
-  HL.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
LD
+Load value into register A from byte pointed by
+  HL and post-decrement HL.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Load value n16 into register
-  SP.
-

-Cycles: 3
-

-Bytes: 3
-

-Flags: None affected.
-
LD
+Load value n16 into register SP.
+
Cycles: 3

+
Bytes: 3

+
Flags: None affected.

+

+

+

-Store SP into addresses
-  n16 (LSB) and
-  n16 + 1 (MSB).
-

-Cycles: 5
-

-Bytes: 3
-

-Flags: None affected.
-
LD
+Store SP into addresses n16 (LSB) and
+  n16 + 1 (MSB).
+
Cycles: 5

+
Bytes: 3

+
Flags: None affected.

+

+

+

-Add the signed value e8 to
-  SP and store the result in
-  HL.
-

-Cycles: 3
-

-Bytes: 2
-

-Flags:
+Add the signed value e8 to SP and store
+  the result in HL.
+
Cycles: 3

+
Bytes: 2

+
Flags:

 
    
-  
  • Z: 0
    • 
-  
  • N: 0
    • 
-  
  • H: Set if overflow from bit
-      3.
    • 
-  
  • C: Set if overflow from bit
-      7.
    • 
+  
  • Z: 0
    • 
+  
  • N: 0
    • 
+  
  • H: Set if overflow from bit 3.
    • 
+  
  • C: Set if overflow from bit 7.
    • 
 

-
LD
+

+

+

-Load register HL into register
-  SP.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: None affected.
-
NOP

+Load register HL into register SP.
+
Cycles: 2

+
Bytes: 1

+
Flags: None affected.

+

+

+

 No operation.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags: None affected.
-
OR
+
Cycles: 1

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Bitwise OR between the value in r8 and
-  A.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Bitwise OR between the value in r8 and
+  A.
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: 0
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: 0
    • 
 

-
OR
+

+

+

-Bitwise OR between the value pointed by HL and
-  A.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: See OR A,r8
-
OR
+Bitwise OR between the value pointed by HL and
+  A.
+
Cycles: 2

+
Bytes: 1

+
Flags: See OR A,r8

+

+

+

-Bitwise OR between the value in n8 and
-  A.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags: See OR A,r8
-
POP
-  AF

-Pop register AF from the stack.
-

-Cycles: 3
-

-Bytes: 1
-

-Flags:
+Bitwise OR between the value in n8 and
+  A.
+
Cycles: 2

+
Bytes: 2

+
Flags: See OR A,r8

+

+

+

+Pop register AF from the stack.
+
Cycles: 3

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: Set from bit 7 of the
-      popped low byte.
    • 
-  
  • N: Set from bit 6 of the
-      popped low byte.
    • 
-  
  • H: Set from bit 5 of the
-      popped low byte.
    • 
-  
  • C: Set from bit 4 of the
-      popped low byte.
    • 
+  
  • Z: Set from bit 7 of the popped low byte.
    • 
+  
  • N: Set from bit 6 of the popped low byte.
    • 
+  
  • H: Set from bit 5 of the popped low byte.
    • 
+  
  • C: Set from bit 4 of the popped low byte.
    • 
 

-
POP
+

+

+

-Pop register r16 from the stack.
-

-Cycles: 3
-

-Bytes: 1
-

-Flags: None affected.
-
PUSH
+Pop register r16 from the stack.
+
Cycles: 3

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Push register AF into the stack. The low byte's bit
-  7 corresponds to the Z flag, its bit 6 to the
-  N flag, bit 5 to the
-  H flag, and bit 4 to the
-  C flag. Bits 3 to 0 are reset.
-

-Cycles: 4
-

-Bytes: 1
-

-Flags: None affected.
-
PUSH
+Push register AF into the stack. The low byte's bit 7
+  corresponds to the Z flag, its bit 6 to the
+  N flag, bit 5 to the H flag, and bit 4 to
+  the C flag. Bits 3 to 0 are reset.
+
Cycles: 4

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Push register r16 into the stack.
-

-Cycles: 4
-

-Bytes: 1
-

-Flags: None affected.
-
RES
+Push register r16 into the stack.
+
Cycles: 4

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Set bit u3 in register
-  r8 to 0.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags: None affected.
-
RES
+Set bit u3 in register r8 to 0.
+
Cycles: 2

+
Bytes: 2

+
Flags: None affected.

+

+

+

-Set bit u3 in the byte pointed by
-  HL to 0.
-

-Cycles: 4
-

-Bytes: 2
-

-Flags: None affected.
-
RET

+Set bit u3 in the byte pointed by HL to
+  0.
+
Cycles: 4

+
Bytes: 2

+
Flags: None affected.

+

+

+

 Return from subroutine.
-

-Cycles: 4
-

-Bytes: 1
-

-Flags: None affected.
-
RET
-  cc

-Return from subroutine if condition cc is met.
-

-Cycles: 5/2
-

-Bytes: 1
-

-Flags: None affected.
-
RETI

+
Cycles: 4

+
Bytes: 1

+
Flags: None affected.

+

+

+

+Return from subroutine if condition cc is met.
+
Cycles: 5/2

+
Bytes: 1

+
Flags: None affected.

+

+

+

 Return from subroutine and enable interrupts.
-

-Cycles: 4
-

-Bytes: 1
-

-Flags: None affected.
-
RL
-  r8

-Rotate register r8 left through carry.
-

-
C <- [7 <- 0] <- C

-

-Cycles: 2
-

-Bytes: 2
-

-Flags:
+
Cycles: 4

+
Bytes: 1

+
Flags: None affected.

+

+

+

+Rotate register r8 left through carry.
+

+
C <- [7 <- 0] <- C

+
Cycles: 2

+
Bytes: 2

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: Set according to
-    result.
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: Set according to result.
    • 
 

-
RL
+

+

+

-Rotate value pointed by HL left through carry.
-

-
C <- [7 <- 0] <- C

-

-Cycles: 4
-

-Bytes: 2
-

-Flags: See RL r8
-
RLA

-Rotate register A left through carry.
-

-
C <- [7 <- 0] <- C

-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Rotate value pointed by HL left through carry.
+

+
C <- [7 <- 0] <- C

+
Cycles: 4

+
Bytes: 2

+
Flags: See RL r8

+

+

+

+Rotate register A left through carry.
+

+
C <- [7 <- 0] <- C

+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: 0
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: Set according to
-    result.
    • 
+  
  • Z: 0
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: Set according to result.
    • 
 

-
RLC
-  r8

-Rotate register r8 left.
-

-
C <- [7 <- 0] <- [7]

-

-Cycles: 2
-

-Bytes: 2
-

-Flags:
+

+

+

+Rotate register r8 left.
+

+
C <- [7 <- 0] <- [7]

+
Cycles: 2

+
Bytes: 2

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: Set according to
-    result.
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: Set according to result.
    • 
 

-
RLC
+

+

+

-Rotate value pointed by HL left.
-

-
C <- [7 <- 0] <- [7]

-

-Cycles: 4
-

-Bytes: 2
-

-Flags: See RLC r8
-
RLCA

-Rotate register A left.
-

-
C <- [7 <- 0] <- [7]

-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Rotate value pointed by HL left.
+

+
C <- [7 <- 0] <- [7]

+
Cycles: 4

+
Bytes: 2

+
Flags: See RLC r8

+

+

+

+Rotate register A left.
+

+
C <- [7 <- 0] <- [7]

+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: 0
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: Set according to
-    result.
    • 
+  
  • Z: 0
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: Set according to result.
    • 
 

-
RR
-  r8

-Rotate register r8 right through carry.
-

-
C -> [7 -> 0] -> C

-

-Cycles: 2
-

-Bytes: 2
-

-Flags:
+

+

+

+Rotate register r8 right through carry.
+

+
C -> [7 -> 0] -> C

+
Cycles: 2

+
Bytes: 2

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: Set according to
-    result.
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: Set according to result.
    • 
 

-
RR
+

+

+

-Rotate value pointed by HL right through carry.
-

-
C -> [7 -> 0] -> C

-

-Cycles: 4
-

-Bytes: 2
-

-Flags: See RR r8
-
RRA

-Rotate register A right through carry.
-

-
C -> [7 -> 0] -> C

-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Rotate value pointed by HL right through carry.
+

+
C -> [7 -> 0] -> C

+
Cycles: 4

+
Bytes: 2

+
Flags: See RR r8

+

+

+

+Rotate register A right through carry.
+

+
C -> [7 -> 0] -> C

+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: 0
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: Set according to
-    result.
    • 
+  
  • Z: 0
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: Set according to result.
    • 
 

-
RRC
-  r8

-Rotate register r8 right.
-

-
[0] -> [7 -> 0] -> C

-

-Cycles: 2
-

-Bytes: 2
-

-Flags:
+

+

+

+Rotate register r8 right.
+

+
[0] -> [7 -> 0] -> C

+
Cycles: 2

+
Bytes: 2

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: Set according to
-    result.
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: Set according to result.
    • 
 

-
RRC
+

+

+

-Rotate value pointed by HL right.
-

-
[0] -> [7 -> 0] -> C

-

-Cycles: 4
-

-Bytes: 2
-

-Flags: See RRC r8
-
RRCA

-Rotate register A right.
-

-
[0] -> [7 -> 0] -> C

-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Rotate value pointed by HL right.
+

+
[0] -> [7 -> 0] -> C

+
Cycles: 4

+
Bytes: 2

+
Flags: See RRC r8

+

+

+

+Rotate register A right.
+

+
[0] -> [7 -> 0] -> C

+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: 0
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: Set according to
-    result.
    • 
+  
  • Z: 0
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: Set according to result.
    • 
 

-
RST
+

+

+

-Call restart vector vec.
-

-Cycles: 4
-

-Bytes: 1
-

-Flags: None affected.
-
SBC
+Call restart vector vec.
+
Cycles: 4

+
Bytes: 1

+
Flags: None affected.

+

+

+

-Subtract the value in r8 and the carry flag
-  from A.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Subtract the value in r8 and the carry flag from
+  A.
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 1
    • 
-  
  • H: Set if no borrow from
-      bit 4.
    • 
-  
  • C: Set if no borrow (set if
-      r8 >
-    A).
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 1
    • 
+  
  • H: Set if no borrow from bit 4.
    • 
+  
  • C: Set if no borrow (set if r8
+      > A).
    • 
 

-
SBC
+

+

+

-Subtract the value pointed by HL and the carry flag
-  from A.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: See SBC A,r8
-
SBC
+Subtract the value pointed by HL and the carry flag from
+  A.
+
Cycles: 2

+
Bytes: 1

+
Flags: See SBC A,r8

+

+

+

-Subtract the value n8 and the carry flag from
-  A.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags: See SBC A,r8
-
SCF

+Subtract the value n8 and the carry flag from
+  A.
+
Cycles: 2

+
Bytes: 2

+
Flags: See SBC A,r8

+

+

+

 Set Carry Flag.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: 1
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: 1
    • 
 

-
SET
+

+

+

-Set bit u3 in register
-  r8 to 1.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags: None affected.
-
SET
+Set bit u3 in register r8 to 1.
+
Cycles: 2

+
Bytes: 2

+
Flags: None affected.

+

+

+

-Set bit u3 in the byte pointed by
-  HL to 1.
-

-Cycles: 4
-

-Bytes: 2
-

-Flags: None affected.
-
SLA
-  r8

-Shift left arithmetic register r8.
-

-
C <- [7 <- 0] <- 0

-

-Cycles: 2
-

-Bytes: 2
-

-Flags:
+Set bit u3 in the byte pointed by HL to
+  1.
+
Cycles: 4

+
Bytes: 2

+
Flags: None affected.

+

+

+

+Shift left arithmetic register r8.
+

+
C <- [7 <- 0] <- 0

+
Cycles: 2

+
Bytes: 2

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: Set according to
-    result.
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: Set according to result.
    • 
 

-
SLA
+

+

+

-Shift left arithmetic value pointed by HL.
-

-
C <- [7 <- 0] <- 0

-

-Cycles: 4
-

-Bytes: 2
-

-Flags: See SLA r8
-
SRA
-  r8

-Shift right arithmetic register r8.
-

-
[7] -> [7 -> 0] -> C

-

-Cycles: 2
-

-Bytes: 2
-

-Flags:
+Shift left arithmetic value pointed by HL.
+

+
C <- [7 <- 0] <- 0

+
Cycles: 4

+
Bytes: 2

+
Flags: See SLA r8

+

+

+

+Shift right arithmetic register r8.
+

+
[7] -> [7 -> 0] -> C

+
Cycles: 2

+
Bytes: 2

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: Set according to
-    result.
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: Set according to result.
    • 
 

-
SRA
+

+

+

-Shift right arithmetic value pointed by HL.
-

-
[7] -> [7 -> 0] -> C

-

-Cycles: 4
-

-Bytes: 2
-

-Flags: See SRA r8
-
SRL
-  r8

-Shift right logic register r8.
-

-
0 -> [7 -> 0] -> C

-

-Cycles: 2
-

-Bytes: 2
-

-Flags:
+Shift right arithmetic value pointed by HL.
+

+
[7] -> [7 -> 0] -> C

+
Cycles: 4

+
Bytes: 2

+
Flags: See SRA r8

+

+

+

+Shift right logic register r8.
+

+
0 -> [7 -> 0] -> C

+
Cycles: 2

+
Bytes: 2

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: Set according to
-    result.
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: Set according to result.
    • 
 

-
SRL
+

+

+

-Shift right logic value pointed by HL.
-

-
0 -> [7 -> 0] -> C

-

-Cycles: 4
-

-Bytes: 2
-

-Flags: See SRA r8
-
STOP

+Shift right logic value pointed by HL.
+

+
0 -> [7 -> 0] -> C

+
Cycles: 4

+
Bytes: 2

+
Flags: See SRA r8

+

+

+

 Enter CPU very low power mode. Also used to switch between double and normal
   speed CPU modes in GBC.
-

-Cycles: -
-

-Bytes: 2
-

-Flags: None affected.
-
SUB
+
Cycles: -

+
Bytes: 2

+
Flags: None affected.

+

+

+

-Subtract the value in r8 from
-  A.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Subtract the value in r8 from A.
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 1
    • 
-  
  • H: Set if no borrow from
-      bit 4.
    • 
-  
  • C: Set if no borrow (set if
-      r8 >
-    A).
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 1
    • 
+  
  • H: Set if no borrow from bit 4.
    • 
+  
  • C: Set if no borrow (set if r8
+      > A).
    • 
 

-
SUB
+

+

+

-Subtract the value pointed by HL from
-  A.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: See SUB A,r8
-
SUB
+Subtract the value pointed by HL from A.
+
Cycles: 2

+
Bytes: 1

+
Flags: See SUB A,r8

+

+

+

-Subtract the value n8 from
-  A.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags: See SUB A,r8
-
SWAP
+Subtract the value n8 from A.
+
Cycles: 2

+
Bytes: 2

+
Flags: See SUB A,r8

+

+

+

-Swap upper 4 bits in register r8 and the lower
-  ones.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags:
+Swap upper 4 bits in register r8 and the lower ones.
+
Cycles: 2

+
Bytes: 2

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: 0
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: 0
    • 
 

-
SWAP
+

+

+

-Swap upper 4 bits in the byte pointed by HL and the
-  lower ones.
-

-Cycles: 4
-

-Bytes: 2
-

-Flags: See SWAP r8
-
XOR
+Swap upper 4 bits in the byte pointed by HL and the lower
+  ones.
+
Cycles: 4

+
Bytes: 2

+
Flags: See SWAP r8

+

+

+

-Bitwise XOR between the value in r8 and
-  A.
-

-Cycles: 1
-

-Bytes: 1
-

-Flags:
+Bitwise XOR between the value in r8 and
+  A.
+
Cycles: 1

+
Bytes: 1

+
Flags:

 
    
-  
  • Z: Set if result is 0.
    • 
-  
  • N: 0
    • 
-  
  • H: 0
    • 
-  
  • C: 0
    • 
+  
  • Z: Set if result is 0.
    • 
+  
  • N: 0
    • 
+  
  • H: 0
    • 
+  
  • C: 0
    • 
 

-
XOR
+

+

+

-Bitwise XOR between the value pointed by HL and
-  A.
-

-Cycles: 2
-

-Bytes: 1
-

-Flags: See XOR A,r8
-
XOR
+Bitwise XOR between the value pointed by HL and
+  A.
+
Cycles: 2

+
Bytes: 1

+
Flags: See XOR A,r8

+

+

+

-Bitwise XOR between the value in n8 and
-  A.
-

-Cycles: 2
-

-Bytes: 2
-

-Flags: See XOR A,r8
-
SEE
+Bitwise XOR between the value in n8 and
+  A.
+
Cycles: 2

+
Bytes: 2

+
Flags: See XOR A,r8

+

+

+

+

-rgbasm(1), rgbds(7)
-
HISTORY

-rgbds was originally written by Carsten
-  Sørensen as part of the ASMotor package, and was later packaged in
-  RGBDS by Justin Lloyd. It is now maintained by a number of contributors at
-  https://github.com/rednex/rgbds.
+rgbasm(1), rgbds(7) + +
+

+rgbds was originally written by Carsten Sørensen + as part of the ASMotor package, and was later packaged in RGBDS by Justin + Lloyd. It is now maintained by a number of contributors at + https://github.com/rednex/rgbds. +
+
diff --git a/docs/rgbasm.1.html b/docs/rgbasm.1.html index 681567a7..db71d91a 100644 --- a/docs/rgbasm.1.html +++ b/docs/rgbasm.1.html @@ -1,13 +1,14 @@ + - RGBASM(1) @@ -20,133 +21,105 @@
February 23, 2018
-

NAME

-rgbasm — Game - Boy assembler -

SYNOPSIS

+
+

+rgbasm — +
Game Boy assembler
+
+
+

- - + +
rgbasm[-EhLVvw] - [-b - chars] - [-D - name[=value]] - [-g - chars] - [-i - path] - [-M - dependfile] - [-o - outfile] - [-p - pad_value] - filergbasm[-EhLVvw] [-b + chars] [-D + name[=value]] + [-g chars] + [-i path] + [-M dependfile] + [-o outfile] + [-p pad_value] + file
-

DESCRIPTION

-The rgbasm program creates an object file from an +
+
+

+The rgbasm program creates an object file from an assembly source file. Its arguments are as follows:
-
 
-
 
-
-b - chars
-
Change the two characters used for binary constants. The - defaults are 01.
-
 
-
 
-
-D - name[=value]
-
Add string symbol to the compiled source code. This is - equivalent to name - EQUS - “value” in code. If a value - is not specified, a value of 1 is given.
-
 
-
 
-
-E
-
Export all labels, including unreferenced and local - labels.
-
 
-
 
-
-g - chars
-
Change the four characters used for binary constants. The - defaults are 0123.
-
 
-
 
-
-h
-
By default, rgbasm inserts a - ‘nop’ instruction immediately after any ‘halt’ - instruction. The -h option disables this - behavior.
-
 
-
 
-
-i - path
-
Add an include path.
-
 
-
 
-
-L
-
Disable the optimization that turns loads of the form - LD [$FF00+n8],A into the opcode - LDH [$FF00+n8],A in order to have full - control of the result in the final ROM.
-
 
-
 
-
-M - dependfile
-
Print make(1) dependencies to - dependfile.
-
 
-
 
-
-o - outfile
-
Write an object file to the given filename.
-
 
-
 
-
-p - pad_value
-
When padding an image, pad with this value. The default is - 0x00.
-
 
-
 
-
-V
-
Print the version of the program and exit.
-
 
-
 
-
-v
-
Be verbose.
-
 
-
 
-
-w
-
Disable warning output.
+
+ chars
+
Change the two characters used for binary constants. The defaults are + 01.
+
+ name[=value]
+
Add string symbol to the compiled source code. This is equivalent to + name EQUS + “value” in code. If a value is not + specified, a value of 1 is given.
+
+
Export all labels, including unreferenced and local labels.
+
+ chars
+
Change the four characters used for binary constants. The defaults are + 0123.
+
+
By default, rgbasm inserts a ‘nop’ + instruction immediately after any ‘halt’ instruction. The + -h option disables this behavior.
+
+ path
+
Add an include path.
+
+
Disable the optimization that turns loads of the form LD + [$FF00+n8],A into the opcode LDH [$FF00+n8],A in + order to have full control of the result in the final ROM.
+
+ dependfile
+
Print make(1) dependencies to + dependfile.
+
+ outfile
+
Write an object file to the given filename.
+
+ pad_value
+
When padding an image, pad with this value. The default is 0x00.
+
+
Print the version of the program and exit.
+
+
Be verbose.
+
+
Disable warning output.
-

EXAMPLES

+
+
+

Assembling a basic source file is simple: -
-
-
+

+
 $ rgbasm -o bar.o foo.asm
 

 

-

-The resulting object file is not yet a usable ROM image — it must first
-  be run through rgblink(1) and
-  rgbfix(1).
-
SEE
+
The resulting object file is not yet a usable ROM image —
+    it must first be run through rgblink(1) and
+    rgbfix(1).

+
+
+

-rgbasm(5), rgbfix(1), - rgblink(1), - rgbds(5), rgbds(7), - gbz80(7) -

HISTORY

-rgbasm was originally written by Carsten - Sørensen as part of the ASMotor package, and was later packaged in - RGBDS by Justin Lloyd. It is now maintained by a number of contributors at - https://github.com/rednex/rgbds.
+rgbasm(5), rgbfix(1), + rgblink(1), rgbds(5), + rgbds(7), gbz80(7) + +
+

+rgbasm was originally written by Carsten Sørensen + as part of the ASMotor package, and was later packaged in RGBDS by Justin + Lloyd. It is now maintained by a number of contributors at + https://github.com/rednex/rgbds. +
+ diff --git a/docs/rgbasm.5.html b/docs/rgbasm.5.html index 803ec561..f974342e 100644 --- a/docs/rgbasm.5.html +++ b/docs/rgbasm.5.html @@ -1,13 +1,14 @@ + - RGBASM(5) @@ -20,1121 +21,1010 @@
February 24, 2018
-

NAME

-rgbasm — - language documentation -

DESCRIPTION

+
+

+rgbasm — +
language documentation
+
+
+

This is the full description of the language used by - rgbasm(1). The description of the instructions - supported by the GameBoy CPU is in gbz80(7). -

GENERAL

-

Syntax

+ rgbasm(1). The description of the instructions supported by + the GameBoy CPU is in gbz80(7). +
+
+

+
+

The syntax is line‐based, just as in any other assembler, meaning that you do one instruction or pseudo‐op per line: -
-
[label] - [instruction] - [;comment]
-
-Example: -
-
-
+

+
[label]
+  [instruction]
+  [;comment]

+
Example:

+

+
 John: ld a,87 ;Weee
 

 

-

-All pseudo‐ops, mnemonics and registers (reserved keywords) are
-  case‐insensitive and all labels are case‐sensitive.
-

-There are two syntaxes for comments. In both cases, a comment ends at the end of
-  the line. The most common one is: anything that follows a semicolon
-  ‘;’ (that isn't inside a string) is a
-  comment. There is another format: anything that follows a
-  ‘*’ that is placed right at the start of
-  a line is a comment. The assembler removes all comments from the code before
-  doing anything else.
-

-Sometimes lines can be too long and it may be necessary to split them. The
-  syntax to do so is the following one:
-

-

-
-    DB 1, 2, 3, 4 \ 
+
All pseudo‐ops, mnemonics and registers (reserved keywords)
+    are case‐insensitive and all labels are case‐sensitive.

+
There are two syntaxes for comments. In both cases, a comment ends
+    at the end of the line. The most common one is: anything that follows a
+    semicolon ‘;’ (that isn't inside a
+    string) is a comment. There is another format: anything that follows a
+    ‘*’ that is placed right at the start
+    of a line is a comment. The assembler removes all comments from the code
+    before doing anything else.

+
Sometimes lines can be too long and it may be necessary to split
+    them. The syntax to do so is the following one:

+

+
+    DB 1, 2, 3, 4 \
        5, 6, 7, 8
 

 

-

-This works anywhere in the code except inside of strings. To split strings it is
-  needed to use STRCAT() like this:
-

-

-
-    DB STRCAT("Hello ", \ 
+
This works anywhere in the code except inside of strings. To split
+    strings it is needed to use STRCAT() like this:

+

+
+    DB STRCAT("Hello ", \
               "world!")
 

 

-
Sections

-SECTION name,
-  type
-

-SECTION name,
-  type,
-  options
-

-SECTION name,
-  type[addr]
-

-SECTION name,
-  type[addr],
-  options
-

-Before you can start writing code, you must define a section. This tells the
-  assembler what kind of information follows and, if it is code, where to put
-  it.
-

-name is a string enclosed in double quotes and
-  can be a new name or the name of an existing section. All sections assembled
-  at the same time that have the same name and type are considered to be the
-  same section, and their code is put together in the object file generated by
-  the assembler. All other sections must have a unique name, even in different
-  source files, or the linker will treat it as an error.
-

-Possible section types are as follows:
+
+
+

+SECTION name, + type +

SECTION name, + type, options

+

SECTION name, + type[addr]

+

SECTION name, + type[addr], + options

+

Before you can start writing code, you must define a section. This + tells the assembler what kind of information follows and, if it is code, + where to put it.

+

name is a string enclosed in double quotes + and can be a new name or the name of an existing section. All sections + assembled at the same time that have the same name and type are considered + to be the same section, and their code is put together in the object file + generated by the assembler. All other sections must have a unique name, even + in different source files, or the linker will treat it as an error.

+

Possible section types are as follows:

-
 
-
 
-
ROM0
-
A ROM section. addr can - range from $0000–$3FFF (or $0000–$7FFF if tiny ROM mode is - enabled in rgblink(1)).
-
 
-
 
-
ROMX
-
A banked ROM section. addr - can range from $4000–$7FFF. bank - can range from 1 to 511. Not available if tiny ROM mode is enabled in - rgblink(1).
-
 
-
 
-
VRAM
-
A banked video RAM section. - addr can range from $8000–$9FFF. - bank can be 0 or 1 but bank 1 is - unavailable if DMG mode is enabled in - rgblink(1). Memory in this section can only - be allocated with DS, not filled with - data.
-
 
-
 
-
SRAM
-
A banked external (save) RAM section. - addr can range from $A000–$BFFF. - bank can range from 0 to 15. Memory in - this section can only be allocated with DS, - not filled with data.
-
 
-
 
-
WRAM0
-
A general-purpose RAM section. - addr can range from $C000–$CFFF, - or $C000–$DFFF if DMG mode is enabled in - rgblink(1). Memory in this section can only - be allocated with DS, not filled with - data.
-
 
-
 
-
WRAMX
-
A banked general-purpose RAM section. - addr can range from $D000–$DFFF. - bank can range from 1 to 7. Memory in - this section can only be allocated with DS, +
+
A ROM section. addr can range from + $0000–$3FFF (or $0000–$7FFF if tiny ROM mode is enabled in + rgblink(1)).
+
+
A banked ROM section. addr can range from + $4000–$7FFF. bank can range from 1 to 511. + Not available if tiny ROM mode is enabled in + rgblink(1).
+
+
A banked video RAM section. addr can range from + $8000–$9FFF. bank can be 0 or 1 but bank 1 is + unavailable if DMG mode is enabled in rgblink(1). Memory + in this section can only be allocated with DS, not + filled with data.
+
+
A banked external (save) RAM section. addr can range + from $A000–$BFFF. bank can range from 0 to + 15. Memory in this section can only be allocated with + DS, not filled with data.
+
+
A general-purpose RAM section. addr can range from + $C000–$CFFF, or $C000–$DFFF if DMG mode is enabled in + rgblink(1). Memory in this section can only be allocated + with DS, not filled with data.
+
+
A banked general-purpose RAM section. addr can range + from $D000–$DFFF. bank can range from 1 to 7. + Memory in this section can only be allocated with DS, not filled with data. Not available if DMG mode is enabled in - rgblink(1).
-
 
-
 
-
OAM
-
An object attributes RAM section. - addr can range from $FE00-$FE9F. Memory - in this section can only be allocated with - DS, not filled with data.
-
 
-
 
-
HRAM
-
A high RAM section. addr - can range from $FF80–$FFFE. Memory in this section can only be - allocated with DS, not filled with data. -
- Note: If you use this method of allocating HRAM - the assembler will not choose the short - addressing mode in the LD instructions LD - [$FF00+n8],A and LD A,[$FF00+n8] because - the actual address calculation is done by the linker. If you find this - undesirable you can use RSSET, - RB, or RW - instead or use the LDH [$FF00+n8],A and - LDH A,[$FF00+n8] syntax instead. This forces - the assembler to emit the correct instruction and the linker to check if - the value is in the correct range. This optimization can be disabled by - passing the -L flag to - rgbasm(1).
+ rgblink(1). +
+
An object attributes RAM section. addr can range + from $FE00-$FE9F. Memory in this section can only be allocated with + DS, not filled with data.
+
+
A high RAM section. addr can range from + $FF80–$FFFE. Memory in this section can only be allocated with + DS, not filled with data. +

Note: If you use this method of allocating + HRAM the assembler will not choose the short + addressing mode in the LD instructions LD [$FF00+n8],A + and LD A,[$FF00+n8] because the actual address + calculation is done by the linker. If you find this undesirable you can + use RSSET, RB, or + RW instead or use the LDH + [$FF00+n8],A and LDH A,[$FF00+n8] syntax instead. + This forces the assembler to emit the correct instruction and the linker + to check if the value is in the correct range. This optimization can be + disabled by passing the -L flag to + rgbasm(1).

+
-
-options are comma separated and may include: +

options are comma separated and may + include:

-
 
-
 
-
BANK[bank]
-
Specify which bank for the - linker to place the section.
-
 
-
 
-
ALIGN[align]
-
Place the section at an address whose - align least‐significant bits are - zero. It is a syntax error to use this option with - addr.
+
[bank]
+
Specify which bank for the linker to place the + section.
+
[align]
+
Place the section at an address whose align + least‐significant bits are zero. It is a syntax error to use this + option with addr.
-
-If [addr] is not specified, the section is - considered “floating”; the linker will automatically calculate - an appropriate address for the section. Similarly, if - BANK[bank] is - not specified, the linker will automatically find a bank with enough space. -
-Sections can also be placed by using a linkerscript file. The format is - described in rgblink(5). They allow the user to - place floating sections in the desired bank in the order specified in the - script. This is useful if the sections can't be placed at an address manually - because the size may change, but they have to be together. -
-Section examples: -
-
-
+
If [addr] is not specified, the section is
+    considered “floating”; the linker will automatically calculate
+    an appropriate address for the section. Similarly, if
+    BANK[bank] is not specified,
+    the linker will automatically find a bank with enough space.

+
Sections can also be placed by using a linkerscript file. The
+    format is described in rgblink(5). They allow the user to
+    place floating sections in the desired bank in the order specified in the
+    script. This is useful if the sections can't be placed at an address
+    manually because the size may change, but they have to be together.

+
Section examples:

+

+
     SECTION "CoolStuff",ROMX
 

 

-

-This switches to the section called “CoolStuff” (or creates it if
-  it doesn't already exist) and defines it as a code section.
-

-The following example defines a section that can be placed anywhere in any ROMX
-  bank:
-

-

-
+
This switches to the section called “CoolStuff” (or
+    creates it if it doesn't already exist) and defines it as a code
+  section.

+
The following example defines a section that can be placed
+    anywhere in any ROMX bank:

+

+
     SECTION "CoolStuff",ROMX
 

 

-

-If it is needed, the the base address of the section can be specified:
-

-

-
+
If it is needed, the the base address of the section can be
+    specified:

+

+
     SECTION "CoolStuff",ROMX[$4567]
 

 

-

-An example with a fixed bank:
-

-

-
+
An example with a fixed bank:

+

+
     SECTION "CoolStuff",ROMX[$4567],BANK[3]
 

 

-

-And if you only want to force the section into a certain bank, and not it's
-  position within the bank, that's also possible:
-

-

-
+
And if you only want to force the section into a certain bank, and
+    not it's position within the bank, that's also possible:

+

+
     SECTION "CoolStuff",ROMX,BANK[7]
 

 

-

-Alignment examples: one use could be when using DMA to copy data or when it is
-  needed to align the start of an array to 256 bytes to optimize the code that
-  accesses it.
-

-

-
-    SECTION "OAM Data",WRAM0,ALIGN[8] ; align to 256 bytes 
- 
+
Alignment examples: one use could be when using DMA to copy data
+    or when it is needed to align the start of an array to 256 bytes to optimize
+    the code that accesses it.

+

+
+    SECTION "OAM Data",WRAM0,ALIGN[8] ; align to 256 bytes
+
     SECTION "VRAM Data",ROMX,BANK[2],ALIGN[4] ; align to 16 bytes
 

 

-

-Hint: If you think this is a lot of typing for
-  doing a simple “org” type thing you can quite easily write an
-  intelligent macro (called ORG for example) that
-  uses @ for the section name and determines
-  correct section type etc as arguments for
-  SECTION.
-
Section
+
Hint: If you think this is a lot of typing for
+    doing a simple “org” type thing you can quite easily write an
+    intelligent macro (called ORG for example) that uses
+    @ for the section name and determines correct
+    section type etc as arguments for SECTION.

+
+
+

-POPS and PUSHS provide - the interface to the section stack. -
-PUSHS will push the current section context on the - section stack. POPS can then later be used to - restore it. Useful for defining sections in included files when you don't want - to destroy the section context for the program that included your file. The - number of entries in the stack is limited only by the amount of memory in your - machine. -

SYMBOLS

-

Symbols

+POPS and PUSHS provide the + interface to the section stack. +

PUSHS will push the current section + context on the section stack. POPS can then later be + used to restore it. Useful for defining sections in included files when you + don't want to destroy the section context for the program that included your + file. The number of entries in the stack is limited only by the amount of + memory in your machine.

+
+
+
+

+
+

RGBDS supports several types of symbols:
-
Label
-
Used to assign a memory location with a name
-
EQUate
-
Give a constant a name.
-
SET
-
Almost the same as EQUate, but you can change the value of - a SET during assembling.
-
Structure - (the RS group)
-
Define a structure easily.
-
String equate - (EQUS)
-
Give a frequently used string a name. Can also be used as - a mini-macro, like #define in C.
-
MACRO
-
A block of code or pseudo instructions that you invoke - like any other mnemonic. You can give them arguments too.
+
Label
+
Used to assign a memory location with a name
+
EQUate
+
Give a constant a name.
+
SET
+
Almost the same as EQUate, but you can change the value of a SET during + assembling.
+
Structure (the RS group)
+
Define a structure easily.
+
String equate (EQUS)
+
Give a frequently used string a name. Can also be used as a mini-macro, + like #define in C.
+
MACRO
+
A block of code or pseudo instructions that you invoke like any other + mnemonic. You can give them arguments too.
-
-A symbol cannot have the same name as a reserved keyword. +

A symbol cannot have the same name as a reserved keyword.

-
Label
-
-
- One of the assembler's main tasks is to keep track of addresses for you so - you don't have to remember obscure numbers but can make do with a - meaningful name, a label. -
- This can be done in a number of ways: -
-
- 
-GlobalLabel 
-AnotherGlobal: 
-.locallabel 
-.yet_a_local: 
-AnotherGlobal.with_another_local: 
-ThisWillBeExported:: ;note the two colons 
+  
Label

+  

+    
One of the assembler's main tasks is to keep track of
+        addresses for you so you don't have to remember obscure numbers but can
+        make do with a meaningful name, a label.

+    
This can be done in a number of ways:

+    

+    
+GlobalLabel
+AnotherGlobal:
+.locallabel
+.yet_a_local:
+AnotherGlobal.with_another_local:
+ThisWillBeExported:: ;note the two colons
 ThisWillBeExported.too::
     

     

-    

-    In the line where a label is defined there musn't be any whitespace before
-      it. Local labels are only accessible within the scope they are defined. A
-      scope starts after a global label and ends at the next global label.
-      Declaring a label (global or local) with :: does an EXPORT at the same
-      time. Local labels can be declared as scope.local or simply as as .local.
-      If the former notation is used, the scope must be the actual current
-      scope.
-    

-    Labels will normally change their value during the link process and are thus
-      not constant. The exception is the case in which the base address of a
-      section is fixed, so the address of the label is known at assembly time.
-    

-    The subtraction of two labels is only constant (known at assembly time) if
-      they are two local labels that belong to the same scope, or they are two
-      global labels that belong to sections with fixed base addresses.

-  
EQU

-  

-    

-    EQUates are constant symbols. They can, for example, be used for things such
-      as bit-definitions of hardware registers.
-    

-    

-    
-EXIT_OK      EQU $00 
+    
In the line where a label is defined there musn't be any
+        whitespace before it. Local labels are only accessible within the scope
+        they are defined. A scope starts after a global label and ends at the
+        next global label. Declaring a label (global or local) with :: does an
+        EXPORT at the same time. Local labels can be declared as scope.local or
+        simply as as .local. If the former notation is used, the scope must be
+        the actual current scope.

+    
Labels will normally change their value during the link
+        process and are thus not constant. The exception is the case in which
+        the base address of a section is fixed, so the address of the label is
+        known at assembly time.

+    
The subtraction of two labels is only constant (known at
+        assembly time) if they are two local labels that belong to the same
+        scope, or they are two global labels that belong to sections with fixed
+        base addresses.

+  

+  
EQU

+  

+    
EQUates are constant symbols. They can, for example, be used
+        for things such as bit-definitions of hardware registers.

+    

+    
+EXIT_OK      EQU $00
 EXIT_FAILURE EQU $01
     

     

-    

-    Note that a colon (:) following the label-name is not allowed. EQUates
-      cannot be exported and imported. They don't change their value during the
-      link process.

-  
SET

-  

-    

-    SETs are similar to EQUates. They are also constant symbols in the sense
-      that their values are defined during the assembly process. These symbols
-      are normally used in macros.
-    

-    

-    
-ARRAY_SIZE EQU 4 
-COUNT      SET 2 
+    
Note that a colon (:) following the label-name is not allowed.
+        EQUates cannot be exported and imported. They don't change their value
+        during the link process.

+  

+  
SET

+  

+    
SETs are similar to EQUates. They are also constant symbols in
+        the sense that their values are defined during the assembly process.
+        These symbols are normally used in macros.

+    

+    
+ARRAY_SIZE EQU 4
+COUNT      SET 2
 COUNT      SET ARRAY_SIZE+COUNT
     

     

-    

-    Note that a colon (:) following the label-name is not allowed. SETs cannot
-      be exported and imported. Alternatively you can use = as a synonym for
-      SET.
-    

-    

-    
+    
Note that a colon (:) following the label-name is not allowed.
+        SETs cannot be exported and imported. Alternatively you can use = as a
+        synonym for SET.

+    

+    
 COUNT = 2
     

     

   

-  
RSSET,
-    RSRESET, RB,
-    RW

-  

-    

-    The RS group of commands is a handy way of defining structures:
-    

-    

-    
-              RSRESET 
-str_pStuff    RW   1 
-str_tData     RB   256 
-str_bCount    RB   1 
+  
RSSET, RSRESET, RB,
+    RW

+  

+    
The RS group of commands is a handy way of defining
+        structures:

+    

+    
+              RSRESET
+str_pStuff    RW   1
+str_tData     RB   256
+str_bCount    RB   1
 str_SIZEOF    RB   0
     

     

-    

-    The example defines four equated symbols:
-    

-    

-    
-str_pStuff = 0 
-str_tData  = 2 
-str_bCount = 258 
+    
The example defines four equated symbols:

+    

+    
+str_pStuff = 0
+str_tData  = 2
+str_bCount = 258
 str_SIZEOF = 259
     

     

-    

-    There are four commands in the RS group of commands:
+    
There are four commands in the RS group of commands:

     
-      -        -      
-      
-        
-        
+      
+        
+        
-      
-        
-        
+      
+        
+        
-      
-        
-        
+      
+        
+        
-      
-        
-        
+      
+        
+        
-      
-        
-        
+      
+        
+        
-      
-        
-        
+      
+        
+        



CommandMeaning
CommandMeaning
       
RSRESETResets the _RS counter to zero.
Resets the _RS counter to zero.
       
RSSET
-          constexprSets the _RS
-          counter to
-          constexpr.

+          constexprSets the _RS counter
+          to constexpr.
       
RB
-          constexprSets the preceding symbol to
-          _RS and adds
-          constexpr to
-          _RS.

+          constexprSets the preceding symbol to _RS
+          and adds constexpr
+          to _RS.
       
RW
-          constexprSets the preceding symbol to
-          _RS and adds
-          constexpr * 2
-          to _RS.

+          constexprSets the preceding symbol to _RS
+          and adds constexpr
+          * 2 to _RS.
       
RL
-          constexprSets the preceding symbol to
-          _RS and adds
-          constexpr * 4
-          to _RS.

+          constexprSets the preceding symbol to _RS
+          and adds constexpr
+          * 4 to _RS.
       

     

-    

-    Note that a colon (:) following the symbol-name is not allowed.
-      RS symbols cannot be exported and imported.
-      They don't change their value during the link process.

-  
EQUS

-  

-    

-    EQUS is used to define string-symbols. Wherever the assembler meets a string
-      symbol its name is replaced with its value. If you are familiar with C you
-      can think of it as the same as #define .
-    

-    

-    
-COUNTREG EQUS "[hl+]" 
-    ld a,COUNTREG 
- 
-PLAYER_NAME EQUS "\"John\"" 
+    
Note that a colon (:) following the symbol-name is not
+        allowed. RS symbols cannot be exported and imported.
+        They don't change their value during the link process.

+  

+  
EQUS

+  

+    
EQUS is used to define string-symbols. Wherever the assembler
+        meets a string symbol its name is replaced with its value. If you are
+        familiar with C you can think of it as the same as
+        #define .

+    

+    
+COUNTREG EQUS "[hl+]"
+    ld a,COUNTREG
+
+PLAYER_NAME EQUS "\"John\""
     db PLAYER_NAME
     

     

-    

-    Note that : following the label-name is not allowed, and that strings must
-      be quoted to be useful.
-    

-    This will be interpreted as:
-    

-    

-    
-    ld a,[hl+] 
+    
Note that : following the label-name is not allowed, and that
+        strings must be quoted to be useful.

+    
This will be interpreted as:

+    

+    
+    ld a,[hl+]
     db "John"
     

     

-    

-    String-symbols can also be used to define small one-line macros:
-    

-    

-    
+    
String-symbols can also be used to define small one-line
+        macros:

+    

+    
 PUSHA EQUS "push af\npush bc\npush de\npush hl\n"
     

     

-    

-    Note that a colon (:) following the label-name is not allowed. String
-      equates can't be exported or imported.
-    

-    Important note: An EQUS can be expanded to a
-      string that contains another EQUS and it will be expanded as well. This
-      means that, if you aren't careful, you may trap the assembler into an
-      infinite loop if there's a circular dependency in the expansions. Also, a
-      MACRO can have inside an EQUS which references the same MACRO, which has
-      the same problem.

-  
MACRO

-  

-    

-    One of the best features of an assembler is the ability to write macros for
-      it. Macros also provide a method of passing arguments to them and they can
-      then react to the input using IF-constructs.
-    

-    

-    
-MyMacro: MACRO 
-         ld   a,80 
-         call MyFunc 
+    
Note that a colon (:) following the label-name is not allowed.
+        String equates can't be exported or imported.

+    
Important note: An EQUS can be expanded to a
+        string that contains another EQUS and it will be expanded as well. This
+        means that, if you aren't careful, you may trap the assembler into an
+        infinite loop if there's a circular dependency in the expansions. Also,
+        a MACRO can have inside an EQUS which references the same MACRO, which
+        has the same problem.

+  

+  
MACRO

+  

+    
One of the best features of an assembler is the ability to
+        write macros for it. Macros also provide a method of passing arguments
+        to them and they can then react to the input using IF-constructs.

+    

+    
+MyMacro: MACRO
+         ld   a,80
+         call MyFunc
          ENDM
     

     

-    

-    Note that a colon (:) following the macro-name is required. Macros can't be
-      exported or imported. It's valid to call a macro from a macro (yes, even
-      the same one).
-    

-    The above example is a very simple macro. You execute the macro by typing
-      its name.
-    

-    

-    
-         add  a,b 
-         ld   sp,hl 
-         MyMacro ;This will be expanded 
+    
Note that a colon (:) following the macro-name is required.
+        Macros can't be exported or imported. It's valid to call a macro from a
+        macro (yes, even the same one).

+    
The above example is a very simple macro. You execute the
+        macro by typing its name.

+    

+    
+         add  a,b
+         ld   sp,hl
+         MyMacro ;This will be expanded
          sub  a,87
     

     

-    

-    When the assembler meets MyMacro it will insert the macrodefinition (the
-      text enclosed in MACRO /
-      ENDM).
-    

-    Suppose your macro contains a loop.
-    

-    

-    
-LoopyMacro: MACRO 
-            xor  a,a 
-.loop       ld   [hl+],a 
-            dec  c 
-            jr   nz,.loop 
+    
When the assembler meets MyMacro it will insert the
+        macrodefinition (the text enclosed in MACRO /
+        ENDM).

+    
Suppose your macro contains a loop.

+    

+    
+LoopyMacro: MACRO
+            xor  a,a
+.loop       ld   [hl+],a
+            dec  c
+            jr   nz,.loop
             ENDM
     

     

-    

-    This is fine. That is, if you only use the macro once per scope. To get
-      around this problem there is a special label string equate called
-      \@ that you can append to your labels and it
-      will then expand to a unique string.
-    

-    \@ also works in REPT-blocks should you have
-      any loops there.
-    

-    

-    
-LoopyMacro: MACRO 
-            xor  a,a 
-.loop\@     ld   [hl+],a 
-            dec  c 
-            jr   nz,.loop\@ 
+    
This is fine. That is, if you only use the macro once per
+        scope. To get around this problem there is a special label string equate
+        called \@ that you can append to your labels and
+        it will then expand to a unique string.

+    
\@ also works in REPT-blocks should
+        you have any loops there.

+    

+    
+LoopyMacro: MACRO
+            xor  a,a
+.loop\@     ld   [hl+],a
+            dec  c
+            jr   nz,.loop\@
             ENDM
     

     

-    

-    Important note: Since a MACRO can call itself
-      (or a different MACRO that calls the first one) there can be problems of
-      circular dependency. They trap the assembler in an infinite loop, so you
-      have to be careful when using recursion with MACROs. Also, a MACRO can
-      have inside an EQUS which references the same MACRO, which has the same
-      problem.
-    

-    Macro Arguments
-    

-    I'd like LoopyMacro a lot better if I didn't have to pre-load the registers
-      with values and then call it. What I'd like is the ability to pass it
-      arguments and it then loaded the registers itself.
-    

-    And I can do that. In macros you can get the arguments by using the special
-      macro string equates \1 through
-      \9, \1 being the
-      first argument specified on the calling of the macro.
-    

-    

-    
-LoopyMacro: MACRO 
-            ld   hl,\1 
-            ld   c,\2 
-            xor  a,a 
-.loop\@     ld   [hl+],a 
-            dec  c 
-            jr   nz,.loop\@ 
+    
Important note: Since a MACRO can call
+        itself (or a different MACRO that calls the first one) there can be
+        problems of circular dependency. They trap the assembler in an infinite
+        loop, so you have to be careful when using recursion with MACROs. Also,
+        a MACRO can have inside an EQUS which references the same MACRO, which
+        has the same problem.

+    
Macro Arguments

+    
I'd like LoopyMacro a lot better if I didn't have to pre-load
+        the registers with values and then call it. What I'd like is the ability
+        to pass it arguments and it then loaded the registers itself.

+    
And I can do that. In macros you can get the arguments by
+        using the special macro string equates \1
+        through \9, \1 being the
+        first argument specified on the calling of the macro.

+    

+    
+LoopyMacro: MACRO
+            ld   hl,\1
+            ld   c,\2
+            xor  a,a
+.loop\@     ld   [hl+],a
+            dec  c
+            jr   nz,.loop\@
             ENDM
     

     

-    

-    Now I can call the macro specifying two arguments. The first being the
-      address and the second being a bytecount. The macro will then reset all
-      bytes in this range.
-    

-    

-    
+    
Now I can call the macro specifying two arguments. The first
+        being the address and the second being a bytecount. The macro will then
+        reset all bytes in this range.

+    

+    
 LoopyMacro MyVars,54
     

     

-    

-    Arguments are passed as string equates. There's no need to enclose them in
-      quotes. An expression will not be evaluated first but passed directly.
-      This means that it's probably a very good idea to use brackets around
-      \1 to \9 if you
-      perform further calculations on them. For instance, if you pass 1 + 2 as
-      the first argument and then do PRINTV
-      \1 * 2 you will get the value 5 on screen and
-      not 6 as you might have expected.
-    

-    In reality, up to 256 arguments can be passed to a macro, but you can only
-      use the first 9 like this. If you want to use the rest, you need to use
-      the keyword SHIFT.
-    

-    Line continuations work as usual inside macros or lists of arguments of
-      macros. Strings, however, are a bit trickier. The following example shows
-      how to use strings as arguments for a macro:
-    

-    

-    
-PrintMacro : MACRO 
-    PRINTT \1 
-ENDM 
- 
-    PrintMacro STRCAT(\"Hello\"\,  \ 
+    
Arguments are passed as string equates. There's no need to
+        enclose them in quotes. An expression will not be evaluated first but
+        passed directly. This means that it's probably a very good idea to use
+        brackets around \1 to \9
+        if you perform further calculations on them. For instance, if you pass 1
+        + 2 as the first argument and then do PRINTV
+        \1 * 2 you will get the value 5 on screen and
+        not 6 as you might have expected.

+    
In reality, up to 256 arguments can be passed to a macro, but
+        you can only use the first 9 like this. If you want to use the rest, you
+        need to use the keyword SHIFT.

+    
Line continuations work as usual inside macros or lists of
+        arguments of macros. Strings, however, are a bit trickier. The following
+        example shows how to use strings as arguments for a macro:

+    

+    
+PrintMacro : MACRO
+    PRINTT \1
+ENDM
+
+    PrintMacro STRCAT(\"Hello\"\,  \
                       \" world\\n\")
     

     

-    

-    SHIFT is a special command only available in
-      macros. Very useful in REPT-blocks. It will shift the arguments by one to
-      the left. \1 will get the value of
-      \2, \2 will get
-      the value in \3 and so forth.
-    

-    This is the only way of accessing the value of arguments from 10 to
-    256.

+    
SHIFT is a special command only
+        available in macros. Very useful in REPT-blocks. It will shift the
+        arguments by one to the left. \1 will get the
+        value of \2, \2 will get
+        the value in \3 and so forth.

+    
This is the only way of accessing the value of arguments from
+        10 to 256.

+
-

Exporting +

+
+

Importing and exporting of symbols is a feature that is very useful when your project spans many source-files and, for example, you need to jump to a routine defined in another file. -
-Exporting of symbols has to be done manually, importing is done automatically if - the assembler doesn't know where a symbol is defined. -
-EXPORT label [, - label , ...] -
-The assembler will make label accessible to other files during the link process. -
-GLOBAL label [, - label , ...] -
-If label is defined during the assembly it will be exported, if not, it will be - imported. Handy (very!) for include-files. Note that, since importing is done - automatically, this keyword has the same effect as - EXPORT. -

Purging +

Exporting of symbols has to be done manually, importing is done + automatically if the assembler doesn't know where a symbol is defined.

+

EXPORT label [, + label , ...]

+

The assembler will make label accessible to other files during the + link process.

+

GLOBAL label [, + label , ...]

+

If label is defined during the assembly it will be exported, if + not, it will be imported. Handy (very!) for include-files. Note that, since + importing is done automatically, this keyword has the same effect as + EXPORT.

+

+
+

-PURGE allows you to completely remove a symbol from - the symbol table as if it had never existed. USE WITH EXTREME CAUTION!!! I - can't stress this enough, you seriously need to know what you are doing. DON'T - purge symbol that you use in expressions the linker needs to calculate. In - fact, it's probably not even safe to purge anything other than string symbols - and macros. -
-
-
-Kamikaze EQUS  "I don't want to live anymore" 
-AOLer    EQUS  "Me too" 
+PURGE allows you to completely remove a symbol from the
+  symbol table as if it had never existed. USE WITH EXTREME CAUTION!!! I can't
+  stress this enough, you seriously need to know what you are doing. DON'T purge
+  symbol that you use in expressions the linker needs to calculate. In fact,
+  it's probably not even safe to purge anything other than string symbols and
+  macros.
+

+
+Kamikaze EQUS  "I don't want to live anymore"
+AOLer    EQUS  "Me too"
          PURGE Kamikaze, AOLer
 

 

-

-Note that string symbols that are part of a PURGE
-  command WILL NOT BE EXPANDED as the ONLY exception to this rule.
-
Predeclared
+
Note that string symbols that are part of a
+    PURGE command WILL NOT BE EXPANDED as the ONLY
+    exception to this rule.

+
+
+

The following symbols are defined by the assembler: - - - - - - - - - +
TypeNameContents
+ + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + +
TypeNameContents
EQU@PC value
PC value
EQU_PIFixed point π
Fixed point π
SET_RS_RS Counter
_RS Counter
EQU_NARGNumber of arguments passed to macro
Number of arguments passed to macro
EQU__LINE__The current line number
The current line number
EQUS__FILE__The current filename
The current filename
EQUS__DATE__Today's date
Today's date
EQUS__TIME__The current time
The current time
EQUS__ISO_8601_LOCAL__ISO 8601 timestamp (local)
ISO 8601 timestamp (local)
EQUS__ISO_8601_UTC__ISO 8601 timestamp (UTC)
ISO 8601 timestamp (UTC)
EQU__UTC_YEAR__Today's year
Today's year
EQU__UTC_MONTH__Today's month number, 1-12
Today's month number, 1-12
EQU__UTC_DAY__Today's day of the month, 1-31
Today's day of the month, 1-31
EQU__UTC_HOUR__Current hour, 0-23
Current hour, 0-23
EQU__UTC_MINUTE__Current minute, 0-59
Current minute, 0-59
EQU__UTC_SECOND__Current second, 0-59
Current second, 0-59
EQU__RGBDS_MAJOR__Major version number of RGBDS.
Major version number of RGBDS.
EQU__RGBDS_MINOR__Minor version number of RGBDS.
Minor version number of RGBDS.
EQU__RGBDS_PATCH__Patch version number of RGBDS.
Patch version number of RGBDS.
-

DEFINING +

+
+
+

-

Defining +
+

-DB defines a list of bytes that will be stored in - the final image. Ideal for tables and text (which is not zero-terminated). -
-
-
+DB defines a list of bytes that will be stored in the
+  final image. Ideal for tables and text (which is not zero-terminated).
+

+
 DB 1,2,3,4,"This is a string"
 

 

-

-Alternatively, you can use DW to store a list of
-  words (16-bits) or DL to store a list of
-  doublewords/longs (32-bits). Strings are not allowed as arguments to
-  DW and DL.
-

-You can also use DB,
-  DW and DL without
-  arguments, or leaving empty elements at any point in the list. This works
-  exactly like DS 1, DS
-  2 and DS 4 respectively. Consequently,
-  DB, DW and
-  DL can be used in a
-  WRAM0 /
-  WRAMX /
-  HRAM /
-  VRAM /
-  SRAM section.
-
Declaring
+
Alternatively, you can use DW to store a
+    list of words (16-bits) or DL to store a list of
+    doublewords/longs (32-bits). Strings are not allowed as arguments to
+    DW and DL.

+
You can also use DB,
+    DW and DL without arguments,
+    or leaving empty elements at any point in the list. This works exactly like
+    DS 1, DS 2 and DS 4
+    respectively. Consequently, DB,
+    DW and DL can be used in a
+    WRAM0 / WRAMX
+    / HRAM /
+    VRAM / SRAM
+    section.

+
+
+

-DS allocates a number of bytes. The content is +DS allocates a number of bytes. The content is undefined. This is the preferred method of allocationg space in a RAM section. - You can, however, use DB, - DW and DL without - any arguments instead. -
-
-
+  You can, however, use DB, DW
+  and DL without any arguments instead.
+

+
 DS str_SIZEOF ;allocate str_SIZEOF bytes
 

 

-
Including
+
+
+

You probably have some graphics you'd like to include. Use - INCBIN to include a raw binary file as it is. If - the file isn't found in the current directory, the include-path list passed to - the linker on the command line will be searched. -
-
-
-INCBIN "titlepic.bin" 
-INCBIN "sprites/hero.bin" ; UNIX 
+  INCBIN to include a raw binary file as it is. If the
+  file isn't found in the current directory, the include-path list passed to the
+  linker on the command line will be searched.
+

+
+INCBIN "titlepic.bin"
+INCBIN "sprites/hero.bin" ; UNIX
 INCBIN "sprites\\hero.bin" ; Windows
 

 

-

-You can also include only part of a file with
-  INCBIN. The example below includes 256 bytes from
-  data.bin starting from byte 78.
-

-

-
+
You can also include only part of a file with
+    INCBIN. The example below includes 256 bytes from
+    data.bin starting from byte 78.

+

+
 INCBIN "data.bin",78,256
 

 

-
Unions

+
+
+

Unions allow multiple memory allocations to share the same space in memory, like unions in C. This allows you to easily reuse memory for different purposes, depending on the game's state. -
-You create unions using the UNION, - NEXTU and ENDU - keywords. NEXTU lets you create a new block of - allocations, and you may use it as many times within a union as necessary. -
-
-
-UNION 
-Name: ds 8 
-Nickname: ds 8 
-NEXTU 
-Health: dw 
-Something: ds 3 
-Lives: db 
-NEXTU 
-Temporary: ds 19 
+
You create unions using the UNION,
+    NEXTU and ENDU keywords.
+    NEXTU lets you create a new block of allocations,
+    and you may use it as many times within a union as necessary.

+

+
+UNION
+Name: ds 8
+Nickname: ds 8
+NEXTU
+Health: dw
+Something: ds 3
+Lives: db
+NEXTU
+Temporary: ds 19
 ENDU
 

 

-

-This union will use up 19 bytes, as this is the size of the largest block (the
-  last one, containing 'Temporary'). Of course, as 'Name', 'Health', and
-  'Temporary' all point to the same memory locations, writes to any one of these
-  will affect values read from the others.
-

-Unions may be used in any section, but code and data may not be included.
-
THE
+
This union will use up 19 bytes, as this is the size of the
+    largest block (the last one, containing 'Temporary'). Of course, as 'Name',
+    'Health', and 'Temporary' all point to the same memory locations, writes to
+    any one of these will affect values read from the others.

+
Unions may be used in any section, but code and data may not be
+    included.

+
+

+
+

-

Printing +
+

These three instructions type text and values to stdout. Useful for debugging macros or wherever you may feel the need to tell yourself some important information. -
-
-
-PRINTT "I'm the greatest programmer in the whole wide world\n" 
-PRINTI (2 + 3) / 5 
-PRINTV $FF00 + $F0 
+

+
+PRINTT "I'm the greatest programmer in the whole wide world\n"
+PRINTI (2 + 3) / 5
+PRINTV $FF00 + $F0
 PRINTF MUL(3.14, 3987.0)
 

 

 

-  
PRINTT

-  
prints out a string.

-  
PRINTV

-  
prints out an integer value in hexadecimal or, as in the
-      example, the result of a calculation. Unsurprisingly, you can also print
-      out a constant symbols value.

-  
PRINTI

-  
prints out a signed integer value.

-  
PRINTF

-  
prints out a fixed point value.

+  

+  
prints out a string.

+  

+  
prints out an integer value in hexadecimal or, as in the example, the
+      result of a calculation. Unsurprisingly, you can also print out a constant
+      symbols value.

+  

+  
prints out a signed integer value.

+  

+  
prints out a fixed point value.

 

-
Automatically
+
+
+

Suppose you're feeling lazy and you want to unroll a time consuming loop. - REPT is here for that purpose. Everything between - REPT and ENDR will - be repeated a number of times just as if you done a copy/paste operation - yourself. The following example will assemble add - a,c four times: -
-
-
-REPT 4 
-add  a,c 
+  REPT is here for that purpose. Everything between
+  REPT and ENDR will be repeated
+  a number of times just as if you done a copy/paste operation yourself. The
+  following example will assemble add a,c four times:
+

+
+REPT 4
+add  a,c
 ENDR
 

 

-

-You can also use REPT to generate tables on the
-  fly:
-

-

-
-; -- 
-; -- Generate a 256 byte sine table with values between 0 and 128 
-; -- 
-ANGLE SET   0.0 
-      REPT  256 
-      DB    (MUL(64.0,SIN(ANGLE))+64.0)>>16 
-ANGLE SET ANGLE+256.0 
+
You can also use REPT to generate tables
+    on the fly:

+

+
+; --
+; -- Generate a 256 byte sine table with values between 0 and 128
+; --
+ANGLE SET   0.0
+      REPT  256
+      DB    (MUL(64.0,SIN(ANGLE))+64.0)>>16
+ANGLE SET ANGLE+256.0
       ENDR
 

 

-

-REPT is also very useful in recursive macros and,
-  as in macros, you can also use the special label operator
-  \@. REPT-blocks can be nested.
-
Aborting
+
REPT is also very useful in recursive
+    macros and, as in macros, you can also use the special label operator
+    \@. REPT-blocks can be nested.

+
+
+

-FAIL and WARN can be - used to print errors and warnings respectively during the assembly process. - This is especially useful for macros that get an invalid argument. - FAIL and WARN take a - string as the only argument and they will print this string out as a normal - error with a line number. -
-FAIL stops assembling immediately while - WARN shows the message but continues afterwards. -

Including +FAIL and WARN can be used to + print errors and warnings respectively during the assembly process. This is + especially useful for macros that get an invalid argument. + FAIL and WARN take a string as + the only argument and they will print this string out as a normal error with a + line number. +

FAIL stops assembling immediately while + WARN shows the message but continues afterwards.

+

+
+

-Use INCLUDE to process another assembler-file and - then return to the current file when done. If the file isn't found in the - current directory the include-path list will be searched. You may nest - INCLUDE calls infinitely (or until you run out of +Use INCLUDE to process another assembler-file and then + return to the current file when done. If the file isn't found in the current + directory the include-path list will be searched. You may nest + INCLUDE calls infinitely (or until you run out of memory, whichever comes first). -
-
-
+

+
     INCLUDE "irq.inc"
 

 

-
Conditional
+
+
+

-The four commands IF, - ELIF, ELSE, and - ENDC are used to conditionally assemble parts of - your file. This is a powerful feature commonly used in macros. -
-
-
-IF NUM < 0 
-  PRINTT "NUM < 0\n" 
-ELIF NUM == 0 
-  PRINTT "NUM == 0\n" 
-ELSE 
-  PRINTT "NUM > 0\n" 
+The four commands IF, ELIF,
+  ELSE, and ENDC are used to
+  conditionally assemble parts of your file. This is a powerful feature commonly
+  used in macros.
+

+
+IF NUM < 0
+  PRINTT "NUM < 0\n"
+ELIF NUM == 0
+  PRINTT "NUM == 0\n"
+ELSE
+  PRINTT "NUM > 0\n"
 ENDC
 

 

-

-The ELIF and ELSE
-  blocks are optional. IF /
-  ELIF /
-  ELSE /
-  ENDC blocks can be nested.
-

-Note that if an ELSE block is found before an
-  ELIF block, the ELIF
-  block will be ignored. All ELIF blocks must go
-  before the ELSE block. Also, if there is more
-  than one ELSE block, all of them but the first
-  one are ignored.
-
Integer
+
The ELIF and ELSE
+    blocks are optional. IF /
+    ELIF /
+    ELSE /
+    ENDC blocks can be nested.

+
Note that if an ELSE block is found before
+    an ELIF block, the ELIF
+    block will be ignored. All ELIF blocks must go
+    before the ELSE block. Also, if there is more than
+    one ELSE block, all of them but the first one are
+    ignored.

+
+
+

An expression can be composed of many things. Expressions are always evaluated using signed 32-bit math. -
-The most basic expression is just a single number. -
-Numeric Formats -
-There are a number of numeric formats. -
+

The most basic expression is just a single number.

+

Numeric Formats

+

There are a number of numeric formats.

+

    -
  • Hexadecimal: $0123456789ABCDEF. Case-insensitive
    • -
  • Decimal: 0123456789
    • -
  • Octal: &01234567
    • -
  • Binary: %01
    • -
  • Fixedpoint (16.16): 01234.56789
    • -
  • Character constant: "ABYZ"
    • -
  • Gameboy graphics: `0123
    • +
  • Hexadecimal: $0123456789ABCDEF. Case-insensitive
    • +
  • Decimal: 0123456789
    • +
  • Octal: &01234567
    • +
  • Binary: %01
    • +
  • Fixedpoint (16.16): 01234.56789
    • +
  • Character constant: "ABYZ"
    • +
  • Gameboy graphics: `0123
-
-The last one, Gameboy graphics, is quite interesting and useful. The values are - actually pixel values and it converts the “chunky” data to - “planar” data as used in the Gameboy. -
-
-
+
The last one, Gameboy graphics, is quite interesting and useful.
+    The values are actually pixel values and it converts the
+    “chunky” data to “planar” data as used in the
+    Gameboy.

+

+
     DW `01012323
 

 

-

-Admittedly, an expression with just a single number is quite boring. To spice
-  things up a bit there are a few operators you can use to perform calculations
-  between numbers.
-

-Operators
-

-A great number of operators you can use in expressions are available (listed in
-  order of precedence):
-
-  -    -  
-  
-    
-    
+
Admittedly, an expression with just a single number is quite
+    boring. To spice things up a bit there are a few operators you can use to
+    perform calculations between numbers.

+
Operators

+
A great number of operators you can use in expressions are
+    available (listed in order of precedence):

+



OperatorMeaning

+  
+    
+    
-  
-    
+    
-    
+    
-  
-    
-    
+  
+    
+    
-  
-    
-    
-  
-  
-    
-    
-  
-  
-    
-    
-  
-  
-    
-    
-  
-  
-    
+    
-    
+    
-  
-    
+    
+    
+  
+  
+    
+    
+  
+  
+    
+    
+  
+  
+    
+    
+  
+  
+    
-    
+    
-  
-    
+    
-    
+    
-  
-    
+    
-    
+    
-  
-    
-    
+  
+    
+    
OperatorMeaning
   
(
+  
Precedence overridePrecedence override
   
FUNC()Function call
Function call
   
~
-      + -Unary not/plus/minus
*
-      / %Multiply/divide/modulo
<<
-      >>Shift left/right
&
-      | ^Binary and/or/xor
+
+  
Add/subtractUnary not/plus/minus
   
!=
+  
Multiply/divide/modulo
Shift left/right
Binary and/or/xor
Add/subtract
Boolean comparisonBoolean comparison
   
>=
+  
Boolean comparison (Same precedence as the
-      others)Boolean comparison (Same precedence as the others)
   
&&
+  
Boolean and/orBoolean and/or
   
!Unary Boolean not
Unary Boolean not
   

 

-

-The result of the boolean operators is zero if when FALSE and non-zero when
-  TRUE. It is legal to use an integer as the condition for IF blocks. You can
-  use symbols instead of numbers in your expression if you wish.
-

-An expression is said to be constant when it doesn't change its value during
-  linking. This basically means that you can't use labels in those expressions.
-  The instructions in the macro-language all require expressions that are
-  constant. The only exception is the subtraction of labels in the same section
-  or labels that belong to sections with a fixed base addresses, all of which
-  must be defined in the same source file (the calculation cannot be passed to
-  the object file generated by the assembler). In this case, the result is a
-  constant that can be calculated at assembly time.
-
Fixed‐point
+
The result of the boolean operators is zero if when FALSE and
+    non-zero when TRUE. It is legal to use an integer as the condition for IF
+    blocks. You can use symbols instead of numbers in your expression if you
+    wish.

+
An expression is said to be constant when it doesn't change its
+    value during linking. This basically means that you can't use labels in
+    those expressions. The instructions in the macro-language all require
+    expressions that are constant. The only exception is the subtraction of
+    labels in the same section or labels that belong to sections with a fixed
+    base addresses, all of which must be defined in the same source file (the
+    calculation cannot be passed to the object file generated by the assembler).
+    In this case, the result is a constant that can be calculated at assembly
+    time.

+
+
+

Fixed point constants are basically normal 32-bit constants where the upper 16 bits are used for the integer part and the lower 16 bits are used for the @@ -1143,87 +1033,83 @@ Fixed point constants are basically normal 32-bit constants where the upper 16 the operands are integer or fixed-point. You can easily convert a fixed-point number to an integer by shifting it right 16 bits. It follows that you can convert an integer to a fixed-point number by shifting it left. -
-Some things are different for fixed-point math, though, which is why you have - the following functions to use: - - - - - - - +

Some things are different for fixed-point math, though, which is + why you have the following functions to use:

+
NameOperation
+ + + - - - + + - - - + + - - - + + - - - + + - - - + + - - - + + - - - + + - - - + + - - - + +
NameOperation
DIV(x, - y) +
DIV(x, + y) x÷y
MUL(x, - y) +
MUL(x, + y) x×y
SIN(x) +
SIN(x) sin(x)
COS(x) +
COS(x) cos(x)
TAN(x) +
TAN(x) tan(x)
ASIN(x) +
ASIN(x) asin(x)
ACOS(x) +
ACOS(x) acos(x)
ATAN(x) +
ATAN(x) atan(x)
ATAN2(x, - y)Angle between +
ATAN2(x, + y)Angle between (x,y) @@ -1234,244 +1120,235 @@ Some things are different for fixed-point math, though, which is why you have
-
-These functions are extremely useful for automatic generation of various tables. - A circle has 65536.0 degrees. Sine values are between [-1.0; 1.0]. -
-
-
-; -- 
-; -- Generate a 256 byte sine table with values between 0 and 128 
-; -- 
-ANGLE SET   0.0 
-      REPT  256 
-      DB    (MUL(64.0,SIN(ANGLE))+64.0)>>16 
-ANGLE SET ANGLE+256.0 
+
These functions are extremely useful for automatic generation of
+    various tables. A circle has 65536.0 degrees. Sine values are between [-1.0;
+    1.0].

+

+
+; --
+; -- Generate a 256 byte sine table with values between 0 and 128
+; --
+ANGLE SET   0.0
+      REPT  256
+      DB    (MUL(64.0,SIN(ANGLE))+64.0)>>16
+ANGLE SET ANGLE+256.0
       ENDR
 

 

-
String
+
+
+

The most basic string expression is any number of characters contained in double quotes ("for instance"). Like in C, the escape character is \, and there are a number of commands you can use within a string: - - - - - - - +
StringMeaning
+ + + - - - + + + - - - + + + - - - + + + - - - + + + - - - + + + - - - + + + - - - + + + - - + - + - - - + + +
StringMeaning
\\Backslash
Backslash
\"Double quote
Double quote
\,Comma
Comma
\{Curly bracket left
Curly bracket left
\}Curly bracket right
Curly bracket right
\nNewline ($0A)
Newline ($0A)
\tTab ($09)
Tab ($09)
\1 +
Macro argument (Only the body of a macros)Macro argument (Only the body of a macros)
\@Label name suffix (Only in the body of macros and - repts)
Label name suffix (Only in the body of macros and repts)
-
-A funky feature is {symbol} within a string. This - will examine the type of the symbol and insert its value accordingly. If - symbol is a string symbol, the symbols value is simply copied. If it's a - numeric symbol, the value is converted to hexadecimal notation and inserted as - a string. -
-HINT: The {symbol} construct can also be used - outside strings. The symbol's value is again inserted as a string. This is - just a short way of doing “{symbol}”. -
-Whenever the macro-language expects a string you can actually use a string - expression. This consists of one or more of these function (yes, you can nest - them). Note that some of these functions actually return an integer and can be - used as part of an integer expression! +

A funky feature is {symbol} within a string. + This will examine the type of the symbol and insert its value accordingly. + If symbol is a string symbol, the symbols value is simply copied. If it's a + numeric symbol, the value is converted to hexadecimal notation and inserted + as a string.

+

HINT: The {symbol} construct can also be used + outside strings. The symbol's value is again inserted as a string. This is + just a short way of doing “{symbol}”.

+

Whenever the macro-language expects a string you can actually use + a string expression. This consists of one or more of these function (yes, + you can nest them). Note that some of these functions actually return an + integer and can be used as part of an integer expression!

- - - - - - + + + - - - + + + - - - + + + - - - + + + - - - + + + - - - + + + - - - + + + - - - + + +
NameOperation
NameOperation
STRLEN(string)Returns the number of characters in string
STRLEN(string)Returns the number of characters in string
STRCAT(str1, - str2)Appends str2 to str1.
STRCAT(str1, + str2)Appends str2 to str1.
STRCMP(str1, - str2)Returns negative if str1 is alphabetically lower than - str2, zero if they match, positive if str1 is greater than str2.
STRCMP(str1, + str2)Returns negative if str1 is alphabetically lower than str2, zero if they + match, positive if str1 is greater than str2.
STRIN(str1, - str2)Returns the position of str2 in str1 or zero if it's - not present (first character is position 1).
STRIN(str1, + str2)Returns the position of str2 in str1 or zero if it's not present (first + character is position 1).
STRSUB(str, - pos, - len)Returns a substring from str starting at pos (first - character is position 1) and with len characters.
STRSUB(str, + pos, len)Returns a substring from str starting at pos (first character is + position 1) and with len characters.
STRUPR(str)Converts all characters in str to capitals and returns - the new string.
STRUPR(str)Converts all characters in str to capitals and returns the new + string.
STRLWR(str)Converts all characters in str to lower case and - returns the new string.
STRLWR(str)Converts all characters in str to lower case and returns the new + string.
-

Character +

+
+

When writing text that is meant to be displayed in the Game Boy, the ASCII characters used in the source code may not be the same ones used in the tileset used in the ROM. For example, the tiles used for uppercase letters may be placed starting at tile index 128, which makes it difficult to add text strings to the ROM. -
-Character maps allow the code to map strings up to 16 characters long to an - abitrary 8-bit value: -
-
-
-CHARMAP "<LF>", 10 
-CHARMAP "&iacute", 20 
+
Character maps allow the code to map strings up to 16 characters
+    long to an abitrary 8-bit value:

+

+
+CHARMAP "<LF>", 10
+CHARMAP "&iacute", 20
 CHARMAP "A", 128
 

 

-

-Note: Character maps affect all strings in the file
-  from the point in which they are defined. This means that any string that the
-  code may want to print as debug information will also be affected by it.
-

-Note: The output value of a mapping can be 0. If
-  this happens, the assembler will treat this as the end of the string and the
-  rest of it will be trimmed.
-
Other
+
Note: Character maps affect all strings in the
+    file from the point in which they are defined. This means that any string
+    that the code may want to print as debug information will also be affected
+    by it.

+
Note: The output value of a mapping can be 0. If
+    this happens, the assembler will treat this as the end of the string and the
+    rest of it will be trimmed.

+
+
+

There are a few other functions that do various useful things: - - - - - - + + + - - - + + + - - - + + + - - - + + + - - - + + +
NameOperation
NameOperation
BANK(arg)Returns a bank number. If - arg is the symbol - @, this function returns the bank of the - current section. If arg is a string, it - returns the bank of the section that has that name. If - arg is a label, it returns the bank - number the label is in. For labels, as the linker has to resolve this, it - can't be used when the expression has to be constant.
BANK(arg)Returns a bank number. If arg is the symbol + @, this function returns the bank of the current + section. If arg is a string, it returns the bank of + the section that has that name. If arg is a label, + it returns the bank number the label is in. For labels, as the linker has + to resolve this, it can't be used when the expression has to be + constant.
DEF(label)Returns TRUE if label - has been defined.
DEF(label)Returns TRUE if label has been defined.
HIGH(arg)Returns the top 8 bits of the operand if - arg is a label or constant, or the top - 8-bit register if it is a 16-bit register.
HIGH(arg)Returns the top 8 bits of the operand if arg is a + label or constant, or the top 8-bit register if it is a 16-bit + register.
LOW(arg)Returns the bottom 8 bits of the operand if - arg is a label or constant, or the bottom - 8-bit register if it is a 16-bit register (AF isn't a valid register for - this function).
LOW(arg)Returns the bottom 8 bits of the operand if arg is + a label or constant, or the bottom 8-bit register if it is a 16-bit + register (AF isn't a valid register for this function).
-

MISCELLANEOUS

-

Changing +

+

+
+

+
+

-OPT can be used to change some of the options - during assembling the source instead of defining them on the commandline. -
-OPT takes a comma-seperated list of options as its - argument: -
-
-
-PUSHO 
-OPT   g.oOX ;Set the GB graphics constants to use these characters 
-DW    `..ooOOXX 
-POPO 
+OPT can be used to change some of the options during
+  assembling the source instead of defining them on the commandline.
+
OPT takes a comma-seperated list of
+    options as its argument:

+

+
+PUSHO
+OPT   g.oOX ;Set the GB graphics constants to use these characters
+DW    `..ooOOXX
+POPO
 DW    `00112233
 

 

-

-The options that OPT can modify are currently: b,
-  e and g.
-

-POPO and PUSHO provide
-  the interface to the option stack. PUSHO will
-  push the current set of options on the option stack.
-  POPO can then later be used to restore them.
-  Useful if you want to change some options in an include file and you don't
-  want to destroy the options set by the program that included your file. The
-  stacks number of entries is limited only by the amount of memory in your
-  machine.
-
SEE
+
The options that OPT can modify are currently:
+    b, e and g.

+
POPO and PUSHO
+    provide the interface to the option stack. PUSHO
+    will push the current set of options on the option stack.
+    POPO can then later be used to restore them. Useful
+    if you want to change some options in an include file and you don't want to
+    destroy the options set by the program that included your file. The stacks
+    number of entries is limited only by the amount of memory in your
+  machine.

+
+
+
+

-rgbasm(1), rgblink(1), - rgblink(5), - rgbds(5), rgbds(7), - gbz80(7) -

HISTORY

-rgbds was originally written by Carsten - Sørensen as part of the ASMotor package, and was later packaged in - RGBDS by Justin Lloyd. It is now maintained by a number of contributors at - https://github.com/rednex/rgbds.
+rgbasm(1), rgblink(1), + rgblink(5), rgbds(5), + rgbds(7), gbz80(7) + +
+

+rgbds was originally written by Carsten Sørensen + as part of the ASMotor package, and was later packaged in RGBDS by Justin + Lloyd. It is now maintained by a number of contributors at + https://github.com/rednex/rgbds. +
+ diff --git a/docs/rgbds.5.html b/docs/rgbds.5.html index 22098669..f3f4c737 100644 --- a/docs/rgbds.5.html +++ b/docs/rgbds.5.html @@ -1,13 +1,14 @@ + - RGBDS(5) @@ -20,124 +21,127 @@
March 13, 2018
-

NAME

-rgbds — object - file format documentation -

DESCRIPTION

-This is the description of the object files used by - rgbasm(1) and - rgblink(1). Please, note that the specifications - may change. This toolchain is in development and new features may require - adding more information to the current format, or modifying some fields, which - would break compatibility with older versions. -

FILE +
+

+rgbds — +
object file format documentation
+
+
+

+This is the description of the object files used by rgbasm(1) + and rgblink(1). Please, note that the specifications may + change. This toolchain is in development and new features may require adding + more information to the current format, or modifying some fields, which would + break compatibility with older versions. +
+
+

The following types are used: -
-LONG is a 32‐bit integer stored in - little‐endian format (Intel). BYTE is - an 8‐bit integer. STRING is a - 0‐terminated string of BYTE. -
-
-
-; Header 
- 
-BYTE    ID[4]            ; "RGB6" 
-LONG    NumberOfSymbols  ; The number of symbols used in this file 
-LONG    NumberOfSections ; The number of sections used in this file 
- 
-; Symbols 
- 
-REPT    NumberOfSymbols   ; Number of symbols defined in this object file. 
- 
-    STRING  Name          ; The name of this symbol. Local symbols are stored 
-                          ; as "Scope.Symbol". 
- 
-    BYTE    Type          ; 0 = LOCAL symbol only used in this file. 
-                          ; 1 = IMPORT this symbol from elsewhere (unused). 
-                          ; 2 = EXPORT this symbol to other objects. 
- 
-    IF      Type != 1     ; If symbol is defined in this object file. 
- 
-        STRING  FileName  ; File where the symbol is defined. 
- 
-        LONG    LineNum   ; Line number in the file where the symbol is defined. 
- 
-        LONG    SectionID ; The section number (of this object file) in which 
-                          ; this symbol is defined. If it doesn't belong to any 
-                          ; specific section (like a constant), this field has 
-                          ; the value -1. 
- 
-        LONG    Value     ; The symbols value. It's the offset into that 
-                          ; symbol's section. 
- 
-    ENDC 
- 
-ENDR 
- 
-; Sections 
- 
-REPT NumberOfSections 
-    STRING  Name  ; Name of the section 
- 
-    LONG    Size  ; Size in bytes of this section 
- 
-    BYTE    Type  ; 0 = WRAM0 
-                  ; 1 = VRAM 
-                  ; 2 = ROMX 
-                  ; 3 = ROM0 
-                  ; 4 = HRAM 
-                  ; 5 = WRAMX 
-                  ; 6 = SRAM 
-                  ; 7 = OAM 
- 
-    LONG    Org   ; Address to fix this section at. -1 if the linker should 
-                  ; decide (floating address). 
- 
-    LONG    Bank  ; Bank to load this section into. -1 if the linker should 
-                  ; decide (floating bank). This field is only valid for ROMX, 
-                  ; VRAM, WRAMX and SRAM sections. 
- 
-    LONG    Align ; Alignment of this section (expressed as number of low bits 
-                  ; to leave as 0). -1 if not defined. 
- 
-    IF      (Type == ROMX) || (Type == ROM0) ; Sections that can contain data. 
- 
-        BYTE    Data[Size]      ; Raw data of the section. 
- 
-        LONG    NumberOfPatches ; Number of patches to apply. 
- 
-        ; These types of sections may have patches 
- 
-        REPT    NumberOfPatches 
- 
-            STRING  SourceFile   ; Name of the source file (for printing error 
-                                 ; messages). 
- 
-            LONG    Line         ; The line of the source file. 
- 
-            LONG    Offset       ; Offset into the section where patch should 
-                                 ; be applied (in bytes). 
- 
-            BYTE    Type         ; 0 = BYTE patch. 
-                                 ; 1 = little endian WORD patch. 
-                                 ; 2 = little endian LONG patch. 
-                                 ; 3 = JR offset value BYTE patch. 
- 
-            LONG    RPNSize      ; Size of the buffer with the RPN. 
-                                 ; expression. 
- 
-            BYTE    RPN[RPNSize] ; RPN expression. Definition below. 
- 
-        ENDR 
- 
-    ENDC 
- 
+
LONG is a 32‐bit integer stored in
+    little‐endian format (Intel). BYTE is an
+    8‐bit integer. STRING is a 0‐terminated
+    string of BYTE.

+

+
+; Header
+
+BYTE    ID[4]            ; "RGB6"
+LONG    NumberOfSymbols  ; The number of symbols used in this file
+LONG    NumberOfSections ; The number of sections used in this file
+
+; Symbols
+
+REPT    NumberOfSymbols   ; Number of symbols defined in this object file.
+
+    STRING  Name          ; The name of this symbol. Local symbols are stored
+                          ; as "Scope.Symbol".
+
+    BYTE    Type          ; 0 = LOCAL symbol only used in this file.
+                          ; 1 = IMPORT this symbol from elsewhere
+                          ; 2 = EXPORT this symbol to other objects.
+
+    IF      Type != 1     ; If symbol is defined in this object file.
+
+        STRING  FileName  ; File where the symbol is defined.
+
+        LONG    LineNum   ; Line number in the file where the symbol is defined.
+
+        LONG    SectionID ; The section number (of this object file) in which
+                          ; this symbol is defined. If it doesn't belong to any
+                          ; specific section (like a constant), this field has
+                          ; the value -1.
+
+        LONG    Value     ; The symbols value. It's the offset into that
+                          ; symbol's section.
+
+    ENDC
+
+ENDR
+
+; Sections
+
+REPT NumberOfSections
+    STRING  Name  ; Name of the section
+
+    LONG    Size  ; Size in bytes of this section
+
+    BYTE    Type  ; 0 = WRAM0
+                  ; 1 = VRAM
+                  ; 2 = ROMX
+                  ; 3 = ROM0
+                  ; 4 = HRAM
+                  ; 5 = WRAMX
+                  ; 6 = SRAM
+                  ; 7 = OAM
+
+    LONG    Org   ; Address to fix this section at. -1 if the linker should
+                  ; decide (floating address).
+
+    LONG    Bank  ; Bank to load this section into. -1 if the linker should
+                  ; decide (floating bank). This field is only valid for ROMX,
+                  ; VRAM, WRAMX and SRAM sections.
+
+    LONG    Align ; Alignment of this section (expressed as number of low bits
+                  ; to leave as 0). -1 if not defined.
+
+    IF      (Type == ROMX) || (Type == ROM0) ; Sections that can contain data.
+
+        BYTE    Data[Size]      ; Raw data of the section.
+
+        LONG    NumberOfPatches ; Number of patches to apply.
+
+        ; These types of sections may have patches
+
+        REPT    NumberOfPatches
+
+            STRING  SourceFile   ; Name of the source file (for printing error
+                                 ; messages).
+
+            LONG    Line         ; The line of the source file.
+
+            LONG    Offset       ; Offset into the section where patch should
+                                 ; be applied (in bytes).
+
+            BYTE    Type         ; 0 = BYTE patch.
+                                 ; 1 = little endian WORD patch.
+                                 ; 2 = little endian LONG patch.
+                                 ; 3 = JR offset value BYTE patch.
+
+            LONG    RPNSize      ; Size of the buffer with the RPN.
+                                 ; expression.
+
+            BYTE    RPN[RPNSize] ; RPN expression. Definition below.
+
+        ENDR
+
+    ENDC
+
 ENDR
 

 

-
RPN
+

+

 Expressions in the object file are stored as RPN. This is an expression of the
   form “2 5 +”. This will first push the value “2”
@@ -146,159 +150,160 @@ Expressions in the object file are stored as RPN. This is an expression of the
   effectively replacing the two top arguments with their sum. In the RGB format,
   RPN expressions are stored as BYTEs with some bytes being special prefixes for
   integers and symbols.
-
-  -    -    -  
-  
-    
-    
+




ValueMeaning

+  
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+  
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+  
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+  
+    
+    
-  
-    
-    
+  
+    
+    
-  
-    
-    
+  
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+    
+    
-  
-    
-    
+  
+    
+    
-  
-    
-    
+  
+    
+    
ValueMeaning
   
$00+
+  

   
$01-
+  

   
$02*
+  

   
$03/
+  

   
$04%
+  

   
$05unary
+  

   
$10|
-      operator
|
+      
   
$11&
+  

   
$12^
+  

   
$13unary
+  

   
$21&&
+  

   
$22||
+  

   
$23unary!
!
   
$30==
+  

   
$31!=
+  

   
$32>
+  

   
$33<
+  

   
$34>=
+  

   
$35<=
+  

   
$40<<
-      comparison

   
$41>>
-      comparison

   
$50BANK(symbol),
-      a LONG Symbol ID follows.

+      a LONG Symbol ID follows.
   
$51BANK(section_name),
+  

       a null-terminated string follows.
   
$52Current
+  
.
   
$60HRAMCheck.
+  

       Check if the value is in HRAM, AND it with 0xFF.
   
$80LONG integer
-      follows.
LONG integer follows.
   
$81LONG Symbol ID
-      follows.
LONG Symbol ID follows.
   

 

-
SEE
+

+
+
+

-rgbasm(1), rgblink(1), - rgbds(7), gbz80(7) -

HISTORY

-rgbds was originally written by Carsten - Sørensen as part of the ASMotor package, and was later packaged in - RGBDS by Justin Lloyd. It is now maintained by a number of contributors at - https://github.com/rednex/rgbds.

+rgbasm(1), rgblink(1), + rgbds(7), gbz80(7) + +
+

+rgbds was originally written by Carsten Sørensen + as part of the ASMotor package, and was later packaged in RGBDS by Justin + Lloyd. It is now maintained by a number of contributors at + https://github.com/rednex/rgbds. +
+ diff --git a/docs/rgbds.7.html b/docs/rgbds.7.html index a9dcdc01..aa51b345 100644 --- a/docs/rgbds.7.html +++ b/docs/rgbds.7.html @@ -1,13 +1,14 @@ + - RGBDS(7) @@ -20,46 +21,52 @@
January 26, 2018
-

NAME

-rgbds — Rednex - Game Boy Development System -

EXAMPLES

+
+

+rgbds — +
Rednex Game Boy Development System
+
+
+

To get a working ROM image from a single assembly source file: -
-
-
-$ rgbasm -o bar.o foo.asm 
-$ rgblink -o baz.gb bar.o 
+

+
+$ rgbasm -o bar.o foo.asm
+$ rgblink -o baz.gb bar.o
 $ rgbfix -v -p 0 baz.gb
 

 

-
SEE
+
+
+

-rgbasm(1), rgbfix(1), - rgblink(1), - rgbds(5), gbz80(7) -

HISTORY

+rgbasm(1), rgbfix(1), + rgblink(1), rgbds(5), + gbz80(7) +
+
+

-
-
1997, Carsten Sørensen (AKA SurfSmurf) writes - ASMotor as a general-purpose assembler/linker system for DOS/Win32.
-
-
1999, Justin Lloyd (AKA Otaku no Zoku) adapts ASMotor to - read and produce GBZ80 assembly/machine code, and releases this version as - RGBDS.
-
-
2009, Vegard Nossum adapts the code to be more UNIX-like - and releases this version as rgbds-linux on GitHub.
-
-
2010, Anthony J. Bentley forks that repository. The fork - becomes the reference implementation of rgbds.
-
-
2017, Bentley's repository is moved to a neutral name. It - is now maintained by a number of contributors at - https://github.com/rednex/rgbds.
-
-
2018, codebase relicensed under the MIT license.
+
+
1997, Carsten Sørensen (AKA SurfSmurf) writes ASMotor as a + general-purpose assembler/linker system for DOS/Win32.
+
+
1999, Justin Lloyd (AKA Otaku no Zoku) adapts ASMotor to read and produce + GBZ80 assembly/machine code, and releases this version as RGBDS.
+
+
2009, Vegard Nossum adapts the code to be more UNIX-like and releases this + version as rgbds-linux on GitHub.
+
+
2010, Anthony J. Bentley forks that repository. The fork becomes the + reference implementation of rgbds.
+
+
2017, Bentley's repository is moved to a neutral name. It is now + maintained by a number of contributors at + https://github.com/rednex/rgbds.
+
+
2018, codebase relicensed under the MIT license.
+
diff --git a/docs/rgbfix.1.html b/docs/rgbfix.1.html index c306ba65..36739fdc 100644 --- a/docs/rgbfix.1.html +++ b/docs/rgbfix.1.html @@ -1,13 +1,14 @@ + - RGBFIX(1) @@ -20,189 +21,158 @@
-

NAME

-rgbfix — Game - Boy checksum fixer -

SYNOPSIS

+
+

+rgbfix — +
Game Boy checksum fixer
+
+
+

- - + +
rgbfix[-CcjsVv] - [-f - fix_spec] - [-i - game_id] - [-k - licensee_str] - [-l - licensee_id] - [-m - mbc_type] - [-n - rom_version] - [-p - pad_value] - [-r - ram_size] - [-t - title_str] - filergbfix[-CcjsVv] [-f + fix_spec] [-i + game_id] [-k + licensee_str] [-l + licensee_id] [-m + mbc_type] [-n + rom_version] [-p + pad_value] [-r + ram_size] [-t + title_str] file
-

DESCRIPTION

-The rgbfix program changes headers of Game Boy ROM +
+
+

+The rgbfix program changes headers of Game Boy ROM images. It also performs other filetype operations, such as truncation. The arguments are as follows:
-
 
-
 
-
-C
-
Set the Game Boy Color–only flag: - 0x143 = 0xC0. If both this and the - -c flag are set, this takes precedence.
-
 
-
 
-
-c
-
Set the Game Boy Color–compatible flag: - 0x143 = 0x80. If both this and the - -C flag are set, - -C takes precedence.
-
 
-
 
-
-f - fix_spec
-
Fix certain header values that the Game Boy checks for - correctness. Alternatively, intentionally trash these values by writing - their binary inverse instead. fix_spec is - a string containing any combination of the following characters: -
-
-
l
-
Fix the Nintendo logo - (0x104–0x133).
-
L
-
Trash the Nintendo logo.
-
h
-
Fix the header checksum (0x14D).
-
H
-
Trash the header checksum.
-
g
-
Fix the global checksum - (0x14E–0x14F).
-
G
-
Trash the global checksum.
+
+
Set the Game Boy Color–only flag: 0x143 = + 0xC0. If both this and the -c flag are set, this + takes precedence.
+
+
Set the Game Boy Color–compatible flag: + 0x143 = 0x80. If both this and the + -C flag are set, -C takes + precedence.
+
+ fix_spec
+
Fix certain header values that the Game Boy checks for correctness. + Alternatively, intentionally trash these values by writing their binary + inverse instead. fix_spec is a string containing any + combination of the following characters: +

+
+
+
Fix the Nintendo logo + (0x104–0x133).
+
+
Trash the Nintendo logo.
+
+
Fix the header checksum (0x14D).
+
+
Trash the header checksum.
+
+
Fix the global checksum + (0x14E–0x14F).
+
+
Trash the global checksum.
-
 
-
 
-
-i - game_id
-
Set the game ID string - (0x13F–0x142) to a given string - of exactly 4 characters. If both this and the title are set, the game ID - will overwrite the overlapping portion of the title.
-
 
-
 
-
-j
-
Set the non-Japanese region flag: 0x14A = - 1.
-
 
-
 
-
-k - licensee_str
-
Set the new licensee string - (0x144–0x145) to a given - string, truncated to at most two characters.
-
 
-
 
-
-l - licensee_id
-
Set the old licensee code, 0x14B, to a - given value from 0 to 0xFF. This value is deprecated and should be set to - 0x33 in all new software.
-
 
-
 
-
-m - mbc_type
-
Set the MBC type, 0x147, to a given value - from 0 to 0xFF.
-
 
-
 
-
-n - rom_version
-
Set the ROM version, 0x14C, to a given - value from 0 to 0xFF.
-
 
-
 
-
-p - pad_value
-
Pad the image to a valid size with a given pad value from 0 - to 0xFF. rgbfix will automatically pick a - size from 32KiB, 64KiB, 128KiB, ..., 8192KiB and give a warning - thereafter. The cartridge size byte (0x148) will be - changed to reflect this new size.
-
 
-
 
-
-r - ram_size
-
Set the RAM size, 0x149, to a given value - from 0 to 0xFF.
-
 
-
 
-
-s
-
Set the SGB flag: 0x146 = 3.
-
 
-
 
-
-t - title
-
Set the title string - (0x134–0x143) to a given - string, truncated to at most 16 characters. It is recommended to use 15 - characters instead, to avoid clashing with the CGB flag - (-c or -C). If - both this and the game ID are set, the game ID will overwrite the - overlapping portion of the title.
-
 
-
 
-
-V
-
Print the version of the program and exit.
-
 
-
 
-
-v
-
Equivalent to -f - lhg.
+
+ game_id
+
Set the game ID string + (0x13F–0x142) to a + given string of exactly 4 characters. If both this and the title are set, + the game ID will overwrite the overlapping portion of the title.
+
+
Set the non-Japanese region flag: 0x14A = 1.
+
+ licensee_str
+
Set the new licensee string + (0x144–0x145) to a + given string, truncated to at most two characters.
+
+ licensee_id
+
Set the old licensee code, 0x14B, to a given value + from 0 to 0xFF. This value is deprecated and should be set to 0x33 in all + new software.
+
+ mbc_type
+
Set the MBC type, 0x147, to a given value from 0 + to 0xFF.
+
+ rom_version
+
Set the ROM version, 0x14C, to a given value from + 0 to 0xFF.
+
+ pad_value
+
Pad the image to a valid size with a given pad value from 0 to 0xFF. + rgbfix will automatically pick a size from 32KiB, + 64KiB, 128KiB, ..., 8192KiB and give a warning thereafter. The cartridge + size byte (0x148) will be changed to reflect this + new size.
+
+ ram_size
+
Set the RAM size, 0x149, to a given value from 0 + to 0xFF.
+
+
Set the SGB flag: 0x146 = 3.
+
+ title
+
Set the title string + (0x134–0x143) to a + given string, truncated to at most 16 characters. It is recommended to use + 15 characters instead, to avoid clashing with the CGB flag + (-c or -C). If both this + and the game ID are set, the game ID will overwrite the overlapping + portion of the title.
+
+
Print the version of the program and exit.
+
+
Equivalent to -f lhg.
-

EXAMPLES

+
+
+

Most values in the ROM header are only cosmetic. The bare minimum requirements for a workable image are checksums, the Nintendo logo, and (if needed) the CGB/SGB flags. It is a good idea to pad the image to a valid size as well (“valid” meaning a multiple of 32KiB). -
-The following will make a plain, no-color Game Boy game without checking for a - valid size: -
-
$ rgbfix -v foo.gb
-
-The following will make a SGB-enabled, color-enabled game with a title of - “foobar”, and pad it to a multiple of 32KiB. (The Game Boy - itself does not use the title, but some emulators or ROM managers might.) -
-
$ rgbfix -vcs -l 0x33 -p 0 -t foobar baz.gb
-
-The following will duplicate the header (sans global checksum) of the game - “Survival Kids”: -
-
$ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t +

The following will make a plain, no-color Game Boy game without + checking for a valid size:

+

+
$ rgbfix -v foo.gb
+

The following will make a SGB-enabled, color-enabled game with a + title of “foobar”, and pad it to a multiple of 32KiB. (The + Game Boy itself does not use the title, but some emulators or ROM managers + might.)

+

+
$ rgbfix -vcs -l 0x33 -p 0 -t foobar baz.gb
+

The following will duplicate the header (sans global checksum) of + the game “Survival Kids”:

+

+
$ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t SURVIVALKIDAVKE SurvivalKids.gbc
-

SEE +

+
+

-rgbasm(1), rgblink(1), - rgbds(7) -

HISTORY

-rgbfix was originally released by Carsten +rgbasm(1), rgblink(1), + rgbds(7) +
+
+

+rgbfix was originally released by Carsten Sørensen as a standalone program called gbfix, and was later packaged in RGBDS by Justin Lloyd. It is now maintained by a number of contributors at - https://github.com/rednex/rgbds.
+ https://github.com/rednex/rgbds. + + diff --git a/docs/rgbgfx.1.html b/docs/rgbgfx.1.html index 51aa503f..47845101 100644 --- a/docs/rgbgfx.1.html +++ b/docs/rgbgfx.1.html @@ -1,13 +1,14 @@ + - RGBGFX(1) @@ -20,151 +21,153 @@
March 11, 2018
-

NAME

-rgbgfx — Game - Boy graphics converter -

SYNOPSIS

+
+

+rgbgfx — +
Game Boy graphics converter
+
+
+

- - + +
rgbgfx[-DfFhPTVv] - [-o - outfile] - [-d - depth] - [-p - palfile] - [-t - mapfile] - [-x - tiles] - filergbgfx[-ADfFhmPTuVv] [-o + outfile] [-a + attrmap] [-d + depth] [-p + palfile] [-t + tilemap] [-x + tiles] file
-

DESCRIPTION

-The rgbgfx program converts PNG images into the - Nintendo Game Boy's planar tile format. -
 
-The resulting colors and their palette indices are determined differently - depending on the input PNG file: +
+
+

+The rgbgfx program converts PNG images into the Nintendo + Game Boy's planar tile format. +

The resulting colors and their palette indices are determined + differently depending on the input PNG file:

-
 
-The input image may not contain more colors than the selected bit depth allows. - Transparent pixels are set to palette index 0. -

ARGUMENTS

+

The input image may not contain more colors than the selected bit + depth allows. Transparent pixels are set to palette index 0.

+
+
+

-
 
-
 
-
-D
-
Debug features are enabled.
-
 
-
 
-
-f
-
Fix the input PNG file to be a correctly indexed - image.
-
 
-
 
-
-F
-
Same as -f, but additionally, - the supplied command line parameters are saved within the PNG and will be - loaded and automatically used next time.
-
 
-
 
-
-d - depth
-
The bit depth of the output image (either 1 or 2). By - default, the bit depth is 2 (two bits per pixel).
-
 
-
 
-
-h
-
Lay out tiles horizontally rather than vertically.
-
 
-
 
-
-o - outfile
-
The name of the output file.
-
 
-
 
-
-p - palfile
-
Output the image's palette in standard GBC palette format - - bytes (8 bytes for two bits per pixel, 4 bytes for one bit per pixel) - containing the RGB15 values in little-endian byte order. If the palette - contains too few colors, the remaining entries are set to black.
-
 
-
 
-
-P
-
Same as -p, but the palette - file output name is made by taking the input PNG file's filename, removing - the file extension, and appending .pal.
-
 
-
 
-
-t - mapfile
-
If any tiles are the same, don't place the repeat tiles in - the output file, and make a tilemap file.
-
 
-
 
-
-T
-
Same as -t, but the tilemap - file output name is made by taking the input filename, removing the file - extension, and appending .tilemap.
-
 
-
 
-
-u
-
Truncate repeated tiles. Useful with tilemaps.
-
 
-
 
-
-V
-
Print the version of the program and exit.
-
 
-
 
-
-v
-
Verbose. Print errors when the command line parameters and - the parameters in the PNG file don't match.
-
 
-
 
-
-x - tiles
-
Trim the end of the output file by this many tiles.
+
+ attrmap
+
Generate a file of tile mirroring attributes for OAM or (CGB-only) + background tiles. For each tile in the input file, a byte is written + representing the dimensions that the associated tile in the output file + should be mirrored. Useful in combination with -m + to keep track the mirror direction of mirrored duplicate tiles.
+
+
Same as -a, but the attrmap file output name is + made by taking the input filename, removing the file extension, and + appending .attrmap.
+
+
Debug features are enabled.
+
+
Fix the input PNG file to be a correctly indexed image.
+
+
Same as -f, but additionally, the supplied command + line parameters are saved within the PNG and will be loaded and + automatically used next time.
+
+ depth
+
The bit depth of the output image (either 1 or 2). By default, the bit + depth is 2 (two bits per pixel).
+
+
Lay out tiles horizontally rather than vertically.
+
+
Truncate tiles by checking for tiles that are mirrored versions of others + and omitting these from the output file. Useful with tilemaps and attrmaps + together to keep track of the duplicated tiles and the dimension mirrored. + Tiles are checked for horizontal, vertical, and horizontal-vertical + mirroring. Implies -u.
+
+ outfile
+
The name of the output file.
+
+ palfile
+
Output the image's palette in standard GBC palette format - bytes (8 bytes + for two bits per pixel, 4 bytes for one bit per pixel) containing the + RGB15 values in little-endian byte order. If the palette contains too few + colors, the remaining entries are set to black.
+
+
Same as -p, but the palette file output name is + made by taking the input PNG file's filename, removing the file extension, + and appending .pal.
+
+ tilemap
+
Generate a file of tile indices. For each tile in the input file, a byte + is written representing the index of the associated tile in the output + file. Useful in combination with -u or + -m to keep track of duplicate tiles.
+
+
Same as -t, but the tilemap file output name is + made by taking the input filename, removing the file extension, and + appending .tilemap.
+
+
Truncate tiles by checking for tiles that are exact duplicates of others + and omitting these from the output file. Useful with tilemaps to keep + track of the duplicated tiles.
+
+
Print the version of the program and exit.
+
+
Verbose. Print errors when the command line parameters and the parameters + in the PNG file don't match.
+
+ tiles
+
Trim the end of the output file by this many tiles.
-

EXAMPLES

+
+
+

The following will take a PNG file with a bit depth of 1, 2, or 8, and output planar 2bpp data: -
-
$ rgbgfx -o out.2bpp in.png
-
-The following creates a planar 2bpp file with only unique tiles, and its tilemap - out.tilemap: -
-
$ rgbgfx -T -u -o out.2bpp in.png
-
-The following will do nothing: -
-
$ rgbgfx in.png
-

SEE +

+
$ rgbgfx -o out.2bpp in.png
+

The following creates a planar 2bpp file with only unique tiles, + and its tilemap out.tilemap:

+

+
$ rgbgfx -T -u -o out.2bpp in.png
+

The following creates a planar 2bpp file with only unique tiles + (accounting for tile mirroring) and its associated tilemap + out.tilemap and attrmap + out.attrmap:

+

+
$ rgbgfx -A -T -m -o out.2bpp in.png
+

The following will do nothing:

+

+
$ rgbgfx in.png
+

+
+

-rgbds(7), rgbasm(1), - rgblink(1), - rgbfix(1), gbz80(7) -

HISTORY

-rgbgfx was created by - stag019 to be included in RGBDS. It is now - maintained by a number of contributors at - https://github.com/rednex/rgbds.
+rgbds(7), rgbasm(1), + rgblink(1), rgbfix(1), + gbz80(7) + +
+

+rgbgfx was created by stag019 to + be included in RGBDS. It is now maintained by a number of contributors at + https://github.com/rednex/rgbds. +
+ diff --git a/docs/rgblink.1.html b/docs/rgblink.1.html index c886419b..9e059686 100644 --- a/docs/rgblink.1.html +++ b/docs/rgblink.1.html @@ -1,13 +1,14 @@ + - RGBLINK(1) @@ -20,137 +21,113 @@
January 26, 2018
-

NAME

-rgblink — Game - Boy linker -

SYNOPSIS

+
+

+rgblink — +
Game Boy linker
+
+
+

- - + +
rgblink[-dtVw] - [-m - mapfile] - [-n - symfile] - [-O - overlayfile] - [-o - outfile] - [-p - pad_value] - [-s - symbol] - [-l - linkerscript] - file ...rgblink[-dtVw] [-m + mapfile] [-n + symfile] [-O + overlayfile] [-o + outfile] [-p + pad_value] [-s + symbol] [-l + linkerscript] file ...
-

DESCRIPTION

-The rgblink program links objects created by - rgbasm(1) into a single Game Boy ROM file. -
-By default, ROM0 sections created by the assembler are placed in the 16KiB bank - 0, and ROMX sections are placed in any bank except bank 0. If your ROM will - only be 32KiB, you can use the -t option to - override this. -
-Similarly, WRAM0 sections are placed in the first 4KiB of WRAM bank 0 and WRAMX - sections are placed in any bank except bank 0. If your ROM doesn't use banked - WRAM you can use option -w option to override - this. -
-Also, if your ROM is designed for DMG, you can make sure that you don't use any - prohibited section by using the option -d, which - implies -w but also prohibits the use of VRAM - bank 1. -
-The arguments are as follows: +
+
+

+The rgblink program links objects created by + rgbasm(1) into a single Game Boy ROM file. +

By default, ROM0 sections created by the assembler are placed in + the 16KiB bank 0, and ROMX sections are placed in any bank except bank 0. If + your ROM will only be 32KiB, you can use the -t + option to override this.

+

Similarly, WRAM0 sections are placed in the first 4KiB of WRAM + bank 0 and WRAMX sections are placed in any bank except bank 0. If your ROM + doesn't use banked WRAM you can use option -w option + to override this.

+

Also, if your ROM is designed for DMG, you can make sure that you + don't use any prohibited section by using the option + -d, which implies -w but + also prohibits the use of VRAM bank 1.

+

The arguments are as follows:

-
 
-
 
-
-m - mapfile
-
Write a mapfile to the given filename.
-
 
-
 
-
-n - symfile
-
Write a symbol file to the given filename.
-
 
-
 
-
-O - overlayfile
-
The ROM image to overlay sections over. When an overlay ROM - is provided, all sections must be fixed. This may be used to patch an - existing binary.
-
 
-
 
-
-o - outfile
-
Write ROM image to the given filename.
-
 
-
 
-
-p - pad_value
-
When padding an image, pad with this value. The default is - 0x00.
-
 
-
 
-
-s - symbol
-
???
-
 
-
 
-
-w
-
Expand the WRAM0 section size from 4KiB to the full 8KiB - assigned to WRAM and prohibit the use of WRAMX sections.
-
 
-
 
-
-d
-
Enable DMG mode. Prohibit the use of sections that doesn't - exist on a DMG, such as WRAMX and VRAM bank 1. This option automatically - enables -w.
-
 
-
 
-
-t
-
Expand the ROM0 section size from 16KiB to the full 32KiB - assigned to ROM and prohibit the use of ROMX sections. Useful for ROMs - that fit in 32 KiB.
-
 
-
 
-
-l - linkerscript
-
Specify a linkerscript file that tells the linker how - sections must be placed in the ROM. This file has priority over the - attributes assigned in the source code, but they have to be consistent. - See rgblink(5) for more information about its - format.
-
 
-
 
-
-V
-
Print the version of the program and exit.
+
+ mapfile
+
Write a mapfile to the given filename.
+
+ symfile
+
Write a symbol file to the given filename.
+
+ overlayfile
+
The ROM image to overlay sections over. When an overlay ROM is provided, + all sections must be fixed. This may be used to patch an existing + binary.
+
+ outfile
+
Write ROM image to the given filename.
+
+ pad_value
+
When padding an image, pad with this value. The default is 0x00.
+
+ symbol
+
???
+
+
Expand the WRAM0 section size from 4KiB to the full 8KiB assigned to WRAM + and prohibit the use of WRAMX sections.
+
+
Enable DMG mode. Prohibit the use of sections that doesn't exist on a DMG, + such as WRAMX and VRAM bank 1. This option automatically enables + -w.
+
+
Expand the ROM0 section size from 16KiB to the full 32KiB assigned to ROM + and prohibit the use of ROMX sections. Useful for ROMs that fit in 32 + KiB.
+
+ linkerscript
+
Specify a linkerscript file that tells the linker how sections must be + placed in the ROM. This file has priority over the attributes assigned in + the source code, but they have to be consistent. See + rgblink(5) for more information about its format.
+
+
Print the version of the program and exit.
-

EXAMPLES

+
+
+

All you need for a basic ROM is an object file, which can be made into a ROM image like so: -
-
$ rgblink -o bar.gb foo.o
-
-The resulting bar.gb will not have correct checksums (unless you put them in the - assembly source). You should use rgbfix(1) to fix - these so that the program will actually run in a Game Boy: -
-
$ rgbfix -v bar.gb
-

SEE +

+
$ rgblink -o bar.gb foo.o
+

The resulting bar.gb will not have correct checksums (unless you + put them in the assembly source). You should use rgbfix(1) + to fix these so that the program will actually run in a Game Boy:

+

+
$ rgbfix -v bar.gb
+

+
+

-rgbasm(1), rgblink(5), - rgbfix(1), rgbds(5), - rgbds(7) -

HISTORY

-rgblink was originally written by Carsten +rgbasm(1), rgblink(5), + rgbfix(1), rgbds(5), + rgbds(7) +
+
+

+rgblink was originally written by Carsten Sørensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd. It is now maintained by a number of contributors at - https://github.com/rednex/rgbds.
+ https://github.com/rednex/rgbds. + + diff --git a/docs/rgblink.5.html b/docs/rgblink.5.html index 33fa208a..bfb65e39 100644 --- a/docs/rgblink.5.html +++ b/docs/rgblink.5.html @@ -1,13 +1,14 @@ + - RGBLINK(5) @@ -20,81 +21,80 @@
January 26, 2018
-

NAME

-rgblink — - linkerscript file format -

DESCRIPTION

+
+

+rgblink — +
linkerscript file format
+
+
+

The linkerscript is an external file that allows the user to specify the order of sections without the need for doing so before assembling each object file. -
-The placement of sections specified in the linkerscript is done before the - sections whose placement is defined in the source code. -
-A linkerscript consists on a series of banks followed by a list of sections and, - optionally, commands. They can be lowercase or uppercase, it is ignored. Any - line can contain a comment starting with - ‘;’ that ends at the end of the line: -
-
-
-ROMX $F ; This is a comment 
-  "Functions to read array" 
-  ALIGN 8 
-  "Array aligned to 256 bytes" 
- 
-WRAMX 2 
+
The placement of sections specified in the linkerscript is done
+    before the sections whose placement is defined in the source code.

+
A linkerscript consists on a series of banks followed by a list of
+    sections and, optionally, commands. They can be lowercase or uppercase, it
+    is ignored. Any line can contain a comment starting with
+    ‘;’ that ends at the end of the
+  line:

+

+
+ROMX $F ; This is a comment
+  "Functions to read array"
+  ALIGN 8
+  "Array aligned to 256 bytes"
+
+WRAMX 2
   "Some variables"
 

 

-

-Numbers can be in decimal or hexadecimal format (the prefix is
-  ‘$’). It is an error if any section name
-  or command are found before setting a bank.
-

-Files can be included by using the INCLUDE
-  keyword followed by a string with the path of the file that has to be
-  included.
-

-The possible bank types are: ROM0,
-  ROMX, VRAM,
-  WRAM0, WRAMX,
-  OAM and HRAM. Types
-  ROMX, VRAM,
-  WRAMX and SRAM are
-  banked, which means that it is needed to specify a bank after the type.
-

-When a new bank statement is found, sections found after it will be placed right
-  from the beginning of that bank. If the linkerscript switches to a different
-  bank and then it comes back to the previous one it will continue from the last
-  address that was used.
-

-The only two commands are ORG and
-  ALIGN:
+
Numbers can be in decimal or hexadecimal format (the prefix is
+    ‘$’). It is an error if any section
+    name or command are found before setting a bank.

+
Files can be included by using the INCLUDE
+    keyword followed by a string with the path of the file that has to be
+    included.

+
The possible bank types are: ROM0,
+    ROMX, VRAM, WRAM0,
+    WRAMX, OAM and HRAM.
+    Types ROMX, VRAM,
+    WRAMX and SRAM are banked, which means
+    that it is needed to specify a bank after the type.

+
When a new bank statement is found, sections found after it will
+    be placed right from the beginning of that bank. If the linkerscript
+    switches to a different bank and then it comes back to the previous one it
+    will continue from the last address that was used.

+
The only two commands are ORG and
+    ALIGN:

 
    
-  
  • ORG sets the address in
-      which new sections will be placed. It can not be lower than the current
-      address.
    • 
-  
  • ALIGN will increase the
-      address until it is aligned to the specified boundary (it tries to set to
-      0 the number of bits specified after the command:
-      ALIGN 8 will align to $100).
    • 
+  
  • ORG sets the address in which new sections will be
+      placed. It can not be lower than the current address.
    • 
+  
  • ALIGN will increase the address until it is aligned
+      to the specified boundary (it tries to set to 0 the number of bits
+      specified after the command: ALIGN 8 will align to
+      $100).
    • 
 

-

-Note: The bank, alignment, address and type of sections can be specified both in
-  the source code and in the linkerscript. For a section to be able to be placed
-  with the linkerscript the bank must be left unassigned in the source code or
-  be the same as the one specified in the linkerscript. The address and
-  alignment musn't be set.
-
SEE
+
Note: The bank, alignment, address and type of sections can be
+    specified both in the source code and in the linkerscript. For a section to
+    be able to be placed with the linkerscript the bank must be left unassigned
+    in the source code or be the same as the one specified in the linkerscript.
+    The address and alignment musn't be set.

+
+
+

-rgbasm(1), rgblink(1), - rgbfix(1), rgbds(5), - rgbds(7) -

HISTORY

-rgblink was originally written by Carsten +rgbasm(1), rgblink(1), + rgbfix(1), rgbds(5), + rgbds(7) +
+
+

+rgblink was originally written by Carsten Sørensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd. It is now maintained by a number of contributors at - https://github.com/rednex/rgbds.
+ https://github.com/rednex/rgbds. + +
January 27, 2018