diff --git a/docs/gbz80.7.html b/docs/gbz80.7.html index 0c535630..c4812c97 100644 --- a/docs/gbz80.7.html +++ b/docs/gbz80.7.html @@ -8,8 +8,10 @@ SPDX-License-Identifier: MIT --> + + GBZ80(7) @@ -24,18 +26,18 @@

gbz80 — -
CPU opcode reference
+CPU opcode reference

-This is the list of opcodes supported by rgbasm(1), including +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:

+ to be register A by default. The following two lines have + the same effect:

 OR A,B
@@ -59,26 +61,25 @@ List of abbreviations used in this document.
   
n16

   
16-bit integer constant.

   
e8

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

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

   
u3

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

   
cc

   
Condition codes:
     

-      
Z:

+      
Z

       
Execute if Z is set.

-      
NZ:

+      
NZ

       
Execute if Z is not set.

-      
C:

+      
C

       
Execute if C is set.

-      
NC:

+      
NC

       
Execute if C is not set.

     

   

   
vec

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

@@ -245,25 +246,25 @@ List of abbreviations used in this document.
   

   
LD [n16],A

   

-  
LD [$FF00+n8],A

+  
LDH [n16],A

   

-  
LD [$FF00+C],A

+  
LDH [C],A

   

   
LD A,[r16]

   

   
LD A,[n16]

   

-  
LD A,[$FF00+n8]

+  
LDH A,[n16]

   

-  
LD A,[$FF00+C]

+  
LDH A,[C]

   

-  
LD [HL+],A

+  
LD [HLI],A

   

-  
LD [HL-],A

+  
LD [HLD],A

   

-  
LD A,[HL+]

+  
LD A,[HLI]

   

-  
LD A,[HL-]

+  
LD A,[HLD]
@@ -361,17 +362,21 @@ Add the value in r8 plus the carry flag to

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.
+

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

Cycles: 2

Bytes: 1

@@ -393,17 +398,21 @@ 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.
+

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

Cycles: 2

Bytes: 1

Flags: See ADD A,r8

@@ -423,11 +432,14 @@ 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.
+

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

Cycles: 2

Bytes: 1

@@ -492,11 +512,14 @@ Test bit u3 in register r8, set the

Cycles: 2

Bytes: 2

Flags:

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

-Call address n16. +Call address n16. This pushes the address of the + instruction after the CALL on the stack, such that + RET can pop it later; then, it executes an + implicit JP n16.

Cycles: 6

Bytes: 3

Flags: None affected.

@@ -520,7 +546,7 @@ Call address n16. cc,n16

Call address n16 if condition cc is met. -

Cycles: 6/3

+

Cycles: 6 taken / 3 untaken

Bytes: 3

Flags: None affected.

@@ -530,33 +556,41 @@ Complement Carry Flag.

Cycles: 1

Bytes: 1

Flags:

- +
+
N
+
0
+
H
+
0
+
C
+
Inverted.
+

Subtract the value in r8 from A and set - flags accordingly, but don't store the result. + flags accordingly, but don't store the result. This is useful for ComParing + values.

Cycles: 1

Bytes: 1

Flags:

- +
+
Z
+
Set if result is 0.
+
N
+
1
+
H
+
Set if borrow from bit 4.
+
C
+
Set if borrow (i.e. if r8 > + A).
+

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

Cycles: 2

Bytes: 1

Flags: See CP A,r8

@@ -572,27 +606,32 @@ Subtract the value n8 from A and set

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

Cycles: 1

Bytes: 1

Flags:

- +
+
N
+
1
+
H
+
1
+

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

Cycles: 1

Bytes: 1

Flags:

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

@@ -600,16 +639,19 @@ Decrement value in register r8 by 1.

Cycles: 1

Bytes: 1

Flags:

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

-Decrement the value pointed by HL by 1. +Decrement the byte pointed to by HL by 1.

Cycles: 3

Bytes: 1

Flags: See DEC r8

@@ -631,21 +673,45 @@ Decrement value in register SP by 1.

-Disable Interrupts. +Disable Interrupts by clearing the IME flag.

Cycles: 1

Bytes: 1

Flags: None affected.

-Enable Interrupts. +Enable Interrupts by setting the IME flag. The flag is only + set after the instruction following EI.

Cycles: 1

Bytes: 1

Flags: None affected.

-Enter CPU low power mode. +Enter CPU low-power consumption mode until an interrupt occurs. The exact + behavior of this instruction depends on the state of the IME + flag. +
+
IME set
+
The CPU enters low-power mode until after an interrupt + is about to be serviced. The handler is executed normally, and the CPU + resumes execution after the HALT when that + returns.
+
IME not set
+
The behavior depends on whether an interrupt is pending (i.e. + ‘[IE] & [IF]’ is non-zero). +
+
None pending
+
As soon as an interrupt becomes pending, the CPU resumes execution. + This is like the above, except that the handler is + not called.
+
Some pending
+
The CPU continues execution after the HALT, + but the byte after it is read twice in a row (PC is + not incremented, due to a hardware bug).
+
+
+

Cycles: -

Bytes: 1

Flags: None affected.

@@ -656,16 +722,19 @@ 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.
+

-Increment the value pointed by HL by 1. +Increment the byte pointed to by HL by 1.

Cycles: 3

Bytes: 1

Flags: See INC r8

@@ -687,7 +756,8 @@ Increment value in register SP by 1.

-Absolute jump to address n16. +Jump to address n16; effectively, store + n16 into PC.

Cycles: 4

Bytes: 3

Flags: None affected.

@@ -695,23 +765,25 @@ Absolute jump to address n16.

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

Cycles: 4/3

+Jump to address n16 if condition cc + is met. +

Cycles: 4 taken / 3 untaken

Bytes: 3

Flags: None affected.

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

Cycles: 1

Bytes: 1

Flags: None affected.

-Relative jump by adding e8 to the current address. +Relative Jump by adding e8 to the address of the + instruction following the JR. To clarify, an operand of 0 is + equivalent to no jumping.

Cycles: 3

Bytes: 2

Flags: None affected.

@@ -719,16 +791,16 @@ Relative jump by adding e8 to the current address.

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

Cycles: 3/2

+

Cycles: 3 taken / 2 untaken

Bytes: 2

Flags: None affected.

-Store value in register on the right into register on the left. +Load (copy) value in register on the right into register on the left.

Cycles: 1

Bytes: 1

Flags: None affected.

@@ -752,8 +824,8 @@ Load value n16 into register r16.

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

Cycles: 2

Bytes: 1

Flags: None affected.

@@ -761,7 +833,7 @@ Store value in register r8 into byte pointed by register

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

Cycles: 3

Bytes: 2

@@ -770,8 +842,8 @@ Store value n8 into byte pointed by register

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

Cycles: 2

Bytes: 1

Flags: None affected.

@@ -779,7 +851,7 @@ Load value into register r8 from byte pointed by register

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

Cycles: 2

Bytes: 1

@@ -788,34 +860,41 @@ Store value in register A into address pointed by register

-Store value in register A into address +Store value in register A into byte at 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

+

+Store value in register A into byte at address + n16, provided it is between + $FF00 and $FFFF.

Cycles: 3

Bytes: 2

Flags: None affected.

+

This is sometimes written as ‘ldio [n16], + a’, or ‘ld [$ff00+n8], + a’.

-

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

+Store value in register A into byte at address + $FF00+C.

Cycles: 2

Bytes: 1

Flags: None affected.

+

This is sometimes written as ‘ldio [c], + a’, or ‘ld [$ff00+c], + a’.

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

Cycles: 2

Bytes: 1

@@ -824,62 +903,69 @@ Load value in register A from address pointed by register

-Load value in register A from address +Load value in register A from byte at 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]

+

+Load value in register A from byte at address + n16, provided it is between + $FF00 and $FFFF.

Cycles: 3

Bytes: 2

Flags: None affected.

+

This is sometimes written as ‘ldio a, + [n16]’, or ‘ld a, + [$ff00+n8]’.

-

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

+Load value in register A from byte at address + $FF00+c.

Cycles: 2

Bytes: 1

Flags: None affected.

+

This is sometimes written as ‘ldio a, + [c]’, or ‘ld a, + [$ff00+c]’.

-

+

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

Cycles: 2

Bytes: 1

Flags: None affected.

-

+

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

Cycles: 2

Bytes: 1

Flags: None affected.

-

+

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

Cycles: 2

Bytes: 1

Flags: None affected.

-

+

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

Cycles: 2

Bytes: 1

Flags: None affected.

@@ -895,8 +981,8 @@ Load value n16 into register SP.

-Store SP into addresses n16 (LSB) and - n16 + 1 (MSB). +Store SP & $FF at address n16 and + SP >> 8 at address n16 + 1.

Cycles: 5

Bytes: 3

Flags: None affected.

@@ -905,16 +991,20 @@ Store SP into addresses n16 (LSB) and

Add the signed value e8 to SP and store - the result in HL. + 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.
+

-No operation. +No OPeration.

Cycles: 1

Bytes: 1

Flags: None affected.

@@ -934,23 +1024,27 @@ No operation.

-Bitwise OR between the value in r8 and - A. +Store into A the bitwise OR of 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
+

-Bitwise OR between the value pointed by HL and - A. +Store into A the bitwise OR of the byte pointed to by + HL and A.

Cycles: 2

Bytes: 1

Flags: See OR A,r8

@@ -958,7 +1052,7 @@ Bitwise OR between the value pointed by HL and

-Bitwise OR between the value in n8 and +Store into A the bitwise OR of n8 and A.

Cycles: 2

Bytes: 2

@@ -966,21 +1060,43 @@ Bitwise OR between the value in n8 and

-Pop register AF from the stack. +Pop register AF from the stack. This is roughly equivalent to + the following imaginary instructions: +
+
+inc sp
+ld a, [sp]
+inc sp
+ld f, [sp] ; See below for individual flags
+
+

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 register r16 from the stack. +Pop register r16 from the stack. This is roughly + equivalent to the following imaginary instructions: +
+
+ld LOW(r16), [sp] ; C, E or L
+inc sp
+ld HIGH(r16), [sp] ; B, D or H
+inc sp
+
+

Cycles: 3

Bytes: 1

Flags: None affected.

@@ -988,10 +1104,16 @@ Pop register r16 from the stack.

-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. +Push register AF into the stack. This is roughly equivalent to + the following imaginary instructions: +
+
+dec sp
+ld [sp], a
+dec sp
+ld [sp], flag_Z << 7 | flag_N << 6 | flag_H << 5 | flag_C << 4
+
+

Cycles: 4

Bytes: 1

Flags: None affected.

@@ -999,7 +1121,16 @@ Push register AF into the stack. The low byte's bit 7

-Push register r16 into the stack. +Push register r16 into the stack. This is roughly + equivalent to the following imaginary instructions: +
+
+dec sp
+ld [sp], HIGH(r16) ; B, D or H
+dec sp
+ld [sp], LOW(r16) ; C, E or L
+
+

Cycles: 4

Bytes: 1

Flags: None affected.

@@ -1007,7 +1138,8 @@ Push register r16 into the stack.

-Set bit u3 in register r8 to 0. +Set bit u3 in register r8 to 0. Bit + 0 is the rightmost one, bit 7 the leftmost one.

Cycles: 2

Bytes: 2

Flags: None affected.

@@ -1016,14 +1148,16 @@ Set bit u3 in register r8 to 0.

Set bit u3 in the byte pointed by HL to - 0. + 0. Bit 0 is the rightmost one, bit 7 the leftmost one.

Cycles: 4

Bytes: 2

Flags: None affected.

-Return from subroutine. +Return from subroutine. This is basically a POP PC (if such an + instruction existed). See POP r16 for an + explanation of how POP works.

Cycles: 4

Bytes: 1

Flags: None affected.

@@ -1031,36 +1165,43 @@ Return from subroutine.

Return from subroutine if condition cc is met. -

Cycles: 5/2

+

Cycles: 5 taken / 2 untaken

Bytes: 1

Flags: None affected.

-Return from subroutine and enable interrupts. +Return from subroutine and enable interrupts. This is basically equivalent to + executing EI then + RET, meaning that IME is set + right after this instruction.

Cycles: 4

Bytes: 1

Flags: None affected.

-Rotate register r8 left through carry. +Rotate bits in 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.
+

-Rotate value pointed by HL left through carry. +Rotate byte pointed to by HL left through carry.

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

Cycles: 4

@@ -1075,12 +1216,16 @@ Rotate register A left through carry.

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.
+

@@ -1090,17 +1235,21 @@ Rotate register r8 left.

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.
+

-Rotate value pointed by HL left. +Rotate byte pointed to by HL left.

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

Cycles: 4

@@ -1115,12 +1264,16 @@ Rotate register A left.

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.
+

@@ -1130,17 +1283,21 @@ Rotate register r8 right through carry.

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.
+

-Rotate value pointed by HL right through carry. +Rotate byte pointed to by HL right through carry.

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

Cycles: 4

@@ -1155,12 +1312,16 @@ Rotate register A right through carry.

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.
+

@@ -1170,17 +1331,21 @@ Rotate register r8 right.

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.
+

-Rotate value pointed by HL right. +Rotate byte pointed to by HL right.

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

Cycles: 4

@@ -1195,17 +1360,23 @@ Rotate register A right.

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.
+

-Call restart vector vec. +Call address vec. This is a shorter and faster equivalent + to CALL for suitable values of + vec.

Cycles: 4

Bytes: 1

Flags: None affected.

@@ -1218,18 +1389,22 @@ Subtract the value in r8 and the carry flag from

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 borrow from bit 4.
+
C
+
Set if borrow (i.e. if (r8 + carry) > + A).
+

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

Cycles: 2

Bytes: 1

@@ -1250,16 +1425,20 @@ Set Carry Flag.

Cycles: 1

Bytes: 1

Flags:

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

-Set bit u3 in register r8 to 1. +Set bit u3 in register r8 to 1. Bit + 0 is the rightmost one, bit 7 the leftmost one.

Cycles: 2

Bytes: 2

Flags: None affected.

@@ -1268,30 +1447,34 @@ Set bit u3 in register r8 to 1.

Set bit u3 in the byte pointed by HL to - 1. + 1. Bit 0 is the rightmost one, bit 7 the leftmost one.

Cycles: 4

Bytes: 2

Flags: None affected.

-Shift left arithmetic register r8. +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.
+

-Shift left arithmetic value pointed by HL. +Shift Left Arithmetic byte pointed to by HL.

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

Cycles: 4

@@ -1300,23 +1483,27 @@ Shift left arithmetic value pointed by HL.

-Shift right arithmetic register 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.
+

-Shift right arithmetic value pointed by HL. +Shift Right Arithmetic byte pointed to by HL.

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

Cycles: 4

@@ -1325,23 +1512,27 @@ Shift right arithmetic value pointed by HL.

-Shift right logic register 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.
+

-Shift right logic value pointed by HL. +Shift Right Logic byte pointed to by HL.

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

Cycles: 4

@@ -1363,18 +1554,22 @@ 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 borrow from bit 4.
+
C
+
Set if borrow (set if r8 > + A).
+

-Subtract the value pointed by HL from A. +Subtract the byte pointed to by HL from A.

Cycles: 2

Bytes: 1

Flags: See SUB A,r8

@@ -1390,21 +1585,25 @@ Subtract the value n8 from A.

-Swap upper 4 bits in register r8 and the lower ones. +Swap upper 4 bits in register r8 and the lower 4 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 upper 4 bits in the byte pointed by HL and the lower +Swap upper 4 bits in the byte pointed by HL and the lower 4 ones.

Cycles: 4

Bytes: 2

@@ -1418,17 +1617,21 @@ Bitwise XOR between the value in r8 and

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
+

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

Cycles: 2

Bytes: 1

@@ -1447,7 +1650,7 @@ Bitwise XOR between the value in n8 and

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

@@ -1460,7 +1663,7 @@ Bitwise XOR between the value in n8 and - +
February 23, 2018RGBDS ManualGeneral
diff --git a/docs/rgbasm.1.html b/docs/rgbasm.1.html index e5a7ef0e..b212ccec 100644 --- a/docs/rgbasm.1.html +++ b/docs/rgbasm.1.html @@ -8,8 +8,10 @@ SPDX-License-Identifier: MIT --> + + RGBASM(1) @@ -24,107 +26,224 @@

rgbasm — -
Game Boy assembler
+Game Boy assembler

- + [-gchars] + [-ipath] + [-Mdepend_file] + [-oout_file] + [-ppad_value] + [-rrecursion_depth] + [-Wwarning] + file ...
rgbasm[-EhLVvw] [-b - chars] [-D + [-EhLVvw] [-b + chars] [-D name[=value]] - [-g chars] - [-i path] - [-M dependfile] - [-o outfile] - [-p pad_value] - [-r recursion_depth] - file

-The rgbasm program creates an object file from an +The rgbasm program creates an RGB object file from an assembly source file. The input file can be a file path, - or - denoting stdin. Its - arguments are as follows: + or - denoting stdin. +

Note that options can be abbreviated as long as the abbreviation + is unambiguous: --verb is + --verbose, but + --ver is invalid because it + could also be --version. The + arguments are as follows:

+ chars, + --binary-digits chars
Change the two characters used for binary constants. The defaults are 01.
+ name[=value], + - -define 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.
-
+
Add a string symbol to the compiled source code. This is equivalent to + ‘name EQUS + "value"’ in code, or + ‘name EQUS + "1"’ if value is not + specified.
+
, + --export-all
Export all labels, including unreferenced and local labels.
+ chars, + --gfx-chars 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.
+
Change the four characters used for gfx constants. The defaults are + 0123.
+
, + --halt-without-nop
+
By default, rgbasm inserts a + nop instruction immediately after any + halt instruction. The -h + option disables this behavior.
+ path, + --include 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.
+
, + --preserve-ld
+
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
+ depend_file, + --dependfile + depend_file
Print make(1) dependencies to - dependfile.
+ depend_file.
- outfile
+ out_file, + --output + out_file
Write an object file to the given filename.
+ pad_value, + --pad-value pad_value
When padding an image, pad with this value. The default is 0x00.
+ recursion_depth, + --recursion-depth recursion_depth
Specifies the recursion depth at which RGBASM will assume being in an infinite loop.
-
+
, + --version
Print the version of the program and exit.
-
+
, + --verbose
Be verbose.
+
+ warning, + --warning + warning
+
Set warning flag warning. A warning message will be + printed if warning is an unknown warning flag. See + the DIAGNOSTICS section for a list + of warnings.
-
Disable warning output.
+
Disable all warning output, even when turned into errors.
+
+
+
+

+Warnings are diagnostic messages that indicate possibly erroneous behavior that + does not necessarily compromise the assembling process. The following options + alter the way warnings are processed. +
+
+
Make all warnings into errors.
+
+
Make the specified warning into an error. A warning's name is appended + (example: -Werror=obsolete), and this warning is + implicitly enabled and turned into an error. This is an error if used with + a meta warning, such as -Werror=all.
+
+

The following warnings are “meta” warnings, that + enable a collection of other warnings. If a specific warning is toggled via + a meta flag and a specific one, the more specific one takes priority. The + position on the command-line acts as a tie breaker, the last one taking + effect.

+
+
+
This enables warnings that are likely to indicate an error or undesired + behavior, and that can easily be fixed.
+
+
This enables extra warnings that are less likely to pose a problem, but + that may still be wanted.
+
+
Enables literally every warning.
+
+

The following warnings are actual warning flags; with each + description, the corresponding warning flag is included. Note that each of + these flag also has a negation (for example, + -Wempty-entry enables the warning that + -Wno-empty-entry disables). Only the non-default + flag is listed here. Ignoring the “no-” prefix, entries are + listed alphabetically.

+
+
+
Warns when WARN-type + assertions fail. (See “Aborting the assembly process” in + rgbasm(5) for ASSERT).
+
+
Warn about incorrect arguments to built-in functions, such as + STRSUB() with indexes outside of the string's + bounds. This warning is enabled by -Wall.
+
+
Warn when dividing the smallest negative integer by -1, which yields + itself due to integer overflow.
+
+
Warn when an empty entry is encountered in a db, + dw, dl list. This warning + is enabled by -Wextra.
+
+
Warn when a constant too large to fit in a signed 32-bit integer is + encountered. This warning is enabled by + -Wall.
+
+
Warn when a string too long to fit in internal buffers is encountered. + This warning is enabled by -Wall.
+
+
Warn when obsolete constructs such as the jp [hl] + instruction or HOME section type are encountered. + This warning is enabled by -Wextra.
+
+
Warn when shifting right a negative value. Use a division by 2^N + instead.
+
+
Warn when a shift's operand is negative or greater than 32.
+
+
Warn when an implicit truncation (for example, db) + loses some bits.
+
+
Warn when the WARN built-in is executed. (See + “Aborting the assembly process” in + rgbasm(5) for WARN).

-You can assemble a source file in two ways. Straight forward way: -
-
-$ rgbasm -o bar.o foo.asm
-
-
+You can assemble a source file in two ways. +

Straightforward way:

+
$ rgbasm -o bar.o + foo.asm

Pipes way:

-
-
-$ cat foo.asm | rgbasm -o bar.o -
-$ 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).

+
$ cat foo.asm | rgbasm -o bar.o + -
+
$ 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 then + rgbfix(1).

+
+
+

+Please report bugs on + GitHub.

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

@@ -137,7 +256,7 @@ $ rgbasm -o bar.o - < foo.asm - +
July 8, 2019RGBDS ManualGeneral
diff --git a/docs/rgbasm.5.html b/docs/rgbasm.5.html index 1ecd3bf1..4248edf4 100644 --- a/docs/rgbasm.5.html +++ b/docs/rgbasm.5.html @@ -8,8 +8,10 @@ SPDX-License-Identifier: MIT --> + + RGBASM(5) @@ -24,936 +26,146 @@

rgbasm — -
language documentation
+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). + rgbasm(1). The description of the instructions supported by + the Game Boy CPU is in gbz80(7). +

It is strongly recommended to have some familiarity with the Game + Boy hardware before reading this document. RGBDS is specifically targeted at + the Game Boy, and thus a lot of its features tie directly to its concepts. + This document is not intended to be a Game Boy hardware reference.

+

Generally, “the linker” will refer to + rgblink(1), but any program that processes RGB object + files (described in rgbds(5)) can be used in its + place.

-

-
-

+

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]
+ [; 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.

+

All reserved keywords (pseudo‐ops, mnemonics, registers + etc.) are case‐insensitive, all identifiers (symbol names) are + case-sensitive.

+

Comments are used to give humans information about the code, such + as explanations. The assembler always ignores comments and + their contents.

+

There are two syntaxes for comments. The most common is that + anything that follows a semicolon ‘;’ + not inside a string, is a comment until the end of the line. The other is + that lines beginning with a ‘*’ (not + even spaces before it) are ignored. This second syntax is deprecated (will + be removed in a future version) and should be replaced with the first + one.

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

+ them. To do so, put a backslash at the end of the line:

-    DB 1, 2, 3, 4 \
-       5, 6, 7, 8
+    DB 1, 2, 3, \
+       4, 5, 6, \ ; Put it before any comments
+       7, 8, 9

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

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

-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:

-
-
-
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).
-
-
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:

-
-
[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:

-
-
-    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:

-
-
-    SECTION "CoolStuff",ROMX
-
-
-

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

-
-
-    SECTION "CoolStuff",ROMX[$4567]
-
-
-

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:

-
-
-    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
-
-    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.

-
-
-

-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.

-
-
-

+

+An expression can be composed of many things. Numerical expressions are always + evaluated using signed 32-bit math. Zero is considered to be the only + "false" number, all non-zero numbers (including negative) are + "true". +

An expression is said to be "constant" if + rgbasm knows its value. This is generally always the + case, unless a label is involved, as explained in the + SYMBOLS section.

+

The instructions in the macro-language generally require constant + expressions.

-

-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.
-
-

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
-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
-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
-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.

-
- 
-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
-str_SIZEOF    RB   0
-
-
-

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:

- - - - - - - - - - - - - - - - - - - - - - - - - -
CommandMeaning
Resets the _RS counter to zero.
- constexprSets the _RS counter - to constexpr.
- constexprSets the preceding symbol to _RS - and adds constexpr - to _RS.
- constexprSets the preceding symbol to _RS - and adds constexpr - * 2 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\""
-    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+]
-    db "John"
-
-
-

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. If - this creates an infinite loop, RGBASM will error out once a certain - depth is reached. See the -r command-line option. 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
-         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
-            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\@
-            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\@
-            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.

-
- 
-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. However, some characters need to be escaped, as in - the following example:

-
- 
-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.

-
-
-
-
-

-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.

-
-
-

-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.

-
-
-

-The following symbols are defined by the assembler: +

+There are a number of numeric formats. - - - + + + - - - + + + - - - + + + - - - + + + - - - + + + - - - + + + - - - + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + +
TypeNameContentsFormat typePrefixAccepted characters
PC valueHexadecimal$0123456789ABCDEF
Fixed point πDecimalnone0123456789
_RS CounterOctal&01234567
Number of arguments passed to macroBinary%01
The current line numberFixed point (16.16)none01234.56789
The current filenameCharacter constantnone"ABYZ"
Today's date
The current time
ISO 8601 timestamp (local)
ISO 8601 timestamp (UTC)
Today's year
Today's month number, 1-12
Today's day of the month, 1-31
Current hour, 0-23
Current minute, 0-59
Current second, 0-59
Major version number of RGBDS.
Minor version number of RGBDS.
Patch version number of RGBDS.Gameboy graphics`0123
-
-
-
-

-
-

-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.

-
-
-

-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. -
-
-DS str_SIZEOF ;allocate str_SIZEOF bytes
-
-
-
-
-

-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 "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.

-
-
-INCBIN "data.bin",78,256
-
-
-
-
-

-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
-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.

-
-
-
-

-
-

-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
-PRINTF MUL(3.14, 3987.0)
-
-
-
-
-
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.
-
-
-
-

-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
-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
-      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.

-
-
-

-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 - memory, whichever comes first). -
-
-    INCLUDE "irq.inc"
-
-
-
-
-

-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.

-
-
-

-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.

-

-
    -
  • Hexadecimal: $0123456789ABCDEF. Case-insensitive
    • -
  • Decimal: 0123456789
    • -
  • Octal: &01234567
    • -
  • Binary: %01
    • -
  • Fixedpoint (16.16): 01234.56789
    • -
  • Character constant: "ABYZ"
    • -
  • Gameboy graphics: `0123
    • -
+

The "character constant" form yields the value the + character maps to in the current charmap. For example, by default (refer to + ascii(7)) ‘"A"’ yields 65. See + Character maps for information on + charmaps.

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):

+ After the backtick, 8 digits between 0 and 3 are expected, corresponding to + pixel values. The resulting value is the two bytes of tile data that would + produce that row of pixels. For example, ‘`01012323’ is + equivalent to ‘$0F55’.

+

You can also use symbols, which are implicitly replaced with their + value.

+
+
+

+A great number of operators you can use in expressions are available (listed + from highest to lowest precedence): - - + + - + - + - - - - - - + + - +
OperatorMeaningOperatorMeaning
Function callBuilt-in function call
Unary not/plus/minusUnary complement/plus/minus
Add/subtract
Boolean comparison
Boolean comparison (Same precedence as the others)Comparison
Unary Boolean notUnary 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.

+

~ complements a value by inverting all its + bits.

+

% is used to get the remainder of the + corresponding division. ‘5 % 2’ is 1.

+

Shifting works by shifting all bits in the left operand either + left (‘<<’) or right (‘>>’) by the + right operand's amount. When shifting left, all newly-inserted bits are + reset; when shifting right, they are copies of the original most significant + bit instead. This makes ‘a << b’ and ‘a >> + b’ equivalent to multiplying and dividing by 2 to the power of b, + respectively.

+

Comparison operators return 0 if the comparison is false, and 1 + otherwise.

+

Unlike in a lot of languages, and for technical reasons, + rgbasm still evaluates both operands of + ‘&&’ and ‘||’.

+

! returns 1 if the operand was 0, and 1 otherwise.

-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 - fraction (65536ths). This means that you can use them in normal integer - expression, and some integer operators like plus and minus don't care whether - 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:

+Fixed-point numbers are basically normal (32-bit) integers, which count + 65536th's instead of entire units, offering better precision than integers but + limiting the range of values. The upper 16 bits are used for the integer part + and the lower 16 bits are used for the fraction (65536ths). Since they are + still akin to integers, you can use them in normal integer expressions, and + some integer operators like ‘+’ and ‘-’ don't care + whether the operands are integers or fixed-point. You can easily truncate a + fixed-point number into an integer by shifting it right by 16 bits. It follows + that you can convert an integer to a fixed-point number by shifting it left. +

The following functions are designed to operate with fixed-point + numbers:

- - + +
NameOperationNameOperation
DIV(x, @@ -1120,18 +333,18 @@ Fixed point constants are basically normal 32-bit constants where the upper 16
-

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].

+

These functions are useful for automatic generation of various + tables. Example: assuming a circle has 65536.0 degrees, and sine values are + in range [-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
+; --
+; -- Generate a 256-byte sine table with values between 0 and 128
+; --
+ANGLE = 0.0
+      REPT 256
+      db MUL(64.0, SIN(ANGLE) + 1.0) >> 16
+ANGLE = ANGLE + 256.0 ; 256 = 65536 / table_len, with table_len = 256
       ENDR
@@ -1140,150 +353,175 @@ ANGLE SET ANGLE+256.0

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: + quotes (‘"for instance"’). The + backslash character ‘\’ is special in + that it causes the character following it to be “escaped”, + meaning that it is treated differently from normal. There are a number of + escape sequences you can use within a string: - - + + - - + + - - + + - + - + - + - + - + + + + + - - + + - - + +
StringMeaningStringMeaning
Backslash‘\\’Produces a backslash
Double quote‘\"’Produces a double quote without terminating
‘\,’ Comma
‘\{’ Curly bracket left
‘\}’ Curly bracket right
‘\n’ Newline ($0A)
‘\r’Carriage return ($0D)
‘\t’ Tab ($09)
Macro argument (Only the body of a macros)“\1” – “\9”Macro argument (Only the body of a macro, see + Invoking 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 with a dollar prepended.

+(Note that some of those can be used outside of strings, when noted further in + this document.) +

A funky feature is + ‘{symbol}’ within a string, called + “symbol interpolation”. This will paste + symbol's contents as a string. If it's a string + symbol, the string is simply inserted. If it's a numeric symbol, its value + is converted to hexadecimal notation with a dollar sign ‘$’ + prepended.

+
+
+TOPIC equs "life, the universe, and everything"
+ANSWER = 42
+; Prints "The answer to life, the universe, and everything is $2A"
+PRINTT "The answer to {TOPIC} is {ANSWER}\n"
+
+
+

Symbol interpolations can be nested, too!

It's possible to change the way numeric symbols are converted by - specifying a print type like so: {d:symbol} Valid print - types are:

+ specifying a print type like so: + ‘{d:symbol}’. Valid print types + are:

- - - + + + - + - + - + - + - + + +
Print typeFormatExamplePrint typeFormatExample
‘d’ Decimal 42
‘x’ Lowercase hexadecimal 2a
‘X’ Uppercase hexadecimal 2A
‘b’ Binary101010 -

Note that print types should only be used with numeric values, - not strings.

-

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
STRLEN(string)Returns the number of characters in string
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.
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.
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.
- 		101010
+

Note that print types should only be used with numeric values, not + strings.

+

HINT: The {symbol} construct can also be + used outside strings. The symbol's value is again inserted directly.

+

The following functions operate on string expressions. Most of + them return a string, however some of these functions actually return an + integer and can be used as part of an integer expression!

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameOperation
STRLEN(string)Returns the number of characters in string.
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.
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 len + characters long.
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.

-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:

+When writing text that is meant to be displayed in the Game Boy, the characters + used in the source code may have a different encoding than the default of + ASCII. 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 mapping strings up to 16 characters long to + an abitrary 8-bit value:

 CHARMAP "<LF>", 10
@@ -1291,34 +529,36 @@ CHARMAP "&iacute", 20
 CHARMAP "A", 128
+By default, a character map contains ASCII encoding.

It is possible to create multiple character maps and then switch between them as desired. This can be used to encode debug information in ASCII and use a different encoding for other purposes, for example. - Initially, there is one character map called main and it - is automatically selected as the current character map from the beginning. + Initially, there is one character map called ‘main’ and it is + automatically selected as the current character map from the beginning. There is also a character map stack that can be used to save and restore which character map is currently active.

- - + + + name. - + - + @@ -1343,8 +583,8 @@ CHARMAP "A", 128 There are a few other functions that do various useful things:
CommandMeaningCommandMeaning
name Creates a new, empty character map called - name.
name, basenameCreates a new character map called name, copied - from character map basename.Creates a new character map called name, + copied from character map + basename.
nameSwitch to character map name.Switch to character map name.
- - + + @@ -1352,37 +592,1057 @@ There are a few other functions that do various useful things: @, 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. + it returns the bank number the label is in. The result may be constant if + rgbasm is able to compute it. - + - + - + + + + +
NameOperationNameOperation
BANK(arg)
DEF(label)Returns TRUE if label has been defined.Returns TRUE (1) if label has been defined, FALSE + (0) otherwise. String symbols are not expanded within the + parentheses.
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.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).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).
ISCONST(arg)Returns 1 if arg's value is known by RGBASM (e.g. + if it can be an argument to IF), or 0 if only + RGBLINK can compute its value.
+

+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. +

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

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 are considered to be the + same section, and their code is put together in the object file generated by + the assembler. If the type doesn't match, an error occurs. 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:

+
+
+
A ROM section. addr can range from + $0000 to $3FFF, or + $0000 to $7FFF if tiny ROM + mode is enabled in the linker.
+
+
A banked ROM section. addr can range from + $4000 to $7FFF. + bank can range from 1 to 511. Becomes an alias for + ROM0 if tiny ROM mode is enabled in the + linker.
+
+
A banked video RAM section. addr can range from + $8000 to $9FFF. + bank can be 0 or 1, but bank 1 is unavailable if DMG + mode is enabled in the linker.
+
+
A banked external (save) RAM section. addr can range + from $A000 to $BFFF. + bank can range from 0 to 15.
+
+
A general-purpose RAM section. addr can range from + $C000 to $CFFF, or + $C000 to $DFFF if WRAM0 + mode is enabled in the linker.
+
+
A banked general-purpose RAM section. addr can range + from $D000 to $DFFF. + bank can range from 1 to 7. Becomes an alias for + WRAM0 if WRAM0 mode is enabled in the linker.
+
+
An object attribute RAM section. addr can range from + $FE00 to $FE9F.
+
+
A high RAM section. addr can range from + $FF80 to $FFFE. +

Note: While rgbasm + will automatically optimize ld instructions to + the smaller and faster ldh (see + gbz80(7)) whenever possible, it is generally unable to + do so when a label is involved. Using the ldh + instruction directly is recommended. This forces the assembler to emit a + ldh instruction and the linker to check if the + value is in the correct range.

+
+
+

Since RGBDS produces ROMs, code and data can only be placed in + ROM0 and ROMX sections. To + put some in RAM, have it stored in ROM, and copy it to RAM.

+

options are comma-separated and may + include:

+
+
[bank]
+
Specify which bank for the linker to place the + section in. See above for possible values for bank, + depending on type.
+
[align]
+
Place the section at an address whose align + least‐significant bits are zero. This option can be used with + addr, as long as they don't contradict + eachother.
+
+

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 linker script 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”, creating it + if it doesn't already exist. It can end up in any ROM bank. Code and data + may follow.
    • +
  • If it is needed, the the base address of the section can be specified: +
    + 
    +SECTION "CoolStuff",ROMX[$4567]
+
    +
    +
    • +
  • An example with a fixed bank: +
    + 
    +SECTION "CoolStuff",ROMX[$4567],BANK[3]
+
    +
    +
    • +
  • And if you want to force only the section's bank, and not its position + within the bank, that's also possible: +
    + 
    +SECTION "CoolStuff",ROMX,BANK[7]
+
    +
    +
    • +
  • Alignment examples: The first one could be useful for defining an OAM + buffer to be DMA'd, since it must be aligned to 256 bytes. The second + could also be appropriate for GBC HDMA, or for an optimized copy code that + requires alignment. +
    + 
    +SECTION "OAM Data",WRAM0,ALIGN[8] ; align to 256 bytes
+SECTION "VRAM Data",ROMX,BANK[2],ALIGN[4] ; align to 16 bytes
+
    +
    +
    • +
+
+

+POPS and PUSHS provide the + interface to the section stack. The number of entries in the stack is limited + only by the amount of memory in your machine. +

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 override the section context at the point the file was + included.

+
+
+

+Sometimes you want to have some code in RAM. But then you can't simply put it in + a RAM section, you have to store it in ROM and copy it to RAM at some point. +

This means the code (or data) will not be stored in the place it + gets executed. Luckily, LOAD blocks are the perfect + solution to that. Here's an example of how to use them:

+
+
+SECTION "LOAD example", ROMX
+CopyCode:
+    ld de, RAMCode
+    ld hl, RAMLocation
+    ld c, RAMLocation.end - RAMLocation
+.loop
+    ld a, [de]
+    inc de
+    ld [hli], a
+    dec c
+    jr nz, .loop
+    ret
+
+RAMCode:
+  LOAD "RAM code", WRAM0
+RAMLocation:
+    ld hl, .string
+    ld de, $9864
+.copy
+    ld a, [hli]
+    ld [de], a
+    inc de
+    and a
+    jr nz, .copy
+    ret
+
+.string
+    db "Hello World!", 0
+.end
+  ENDL
+
+
+

A LOAD block feels similar to a + SECTION declaration because it creates a new one. + All data and code generated within such a block is placed in the current + section like usual, but all labels are created as if they were placed in + this newly-created section.

+

In the example above, all of the code and data will end up in the + "LOAD example" section. You will notice the + ‘RAMCode’ and ‘RAMLocation’ labels. The former + is situated in ROM, where the code is stored, the latter in RAM, where the + code will be loaded.

+

You cannot nest LOAD blocks, nor can you + change the current section within them.

+
+
+

+When you're tight on RAM, you may want to define overlapping blocks of + variables, as explained in the Unions + section. However, the UNION keyword only works within + a single file, which prevents e.g. defining temporary variables on a single + memory area across several files. Unionized sections solve this problem. To + declare an unionized section, add a UNION keyword + after the SECTION one; the declaration is otherwise + not different. Unionized sections follow some different rules from normal + sections: +
    +
  • The same unionized section (= having the same name) can be declared + several times per rgbasm invocation, and across + several invocations. Different declarations are treated and merged + identically whether within the same invocation, or different ones.
    • +
  • A section cannot be declared both as unionized or non-unionized.
    • +
  • All declarations must have the same type. For example, even if + rgblink(1)'s -w flag is used, + WRAM0 and WRAMX types are + still considered different.
    • +
  • Different constraints (alignment, bank, etc.) can be specified for each + unionized section declaration, but they must all be compatible. For + example, alignment must be compatible with any fixed address, all + specified banks must be the same, etc.
    • +
  • Unionized sections cannot have type ROM0 or + ROMX.
    • +
+

Different declarations of the same unionized section are not + appended, but instead overlaid on top of eachother, just like + Unions. Similarly, the size of an unionized + section is the largest of all its declarations.

+
+
+
+

+RGBDS supports several types of symbols: +
+
Label
+
Numerical symbol designating a memory location. May or may not have a + value known at assembly time.
+
Constant
+
Numerical symbol whose value has to be known at assembly time.
+
Macro
+
A block of rgbasm code that can be invoked + later.
+
String equate
+
String symbol that can be evaluated, similarly to a macro.
+
+

Symbol names can contain letters, numbers, underscores, hashes and + ‘@’. However, they must begin with either a letter, a number, + or an underscore. Periods are allowed exclusively for labels, as described + below. A symbol cannot have the same name as a reserved keyword. + In the line where a symbol is defined there mustn't be any + whitespace before it, otherwise rgbasm will + treat it as a macro invocation.

+
+
Label declaration
+
One of the assembler's main tasks is to keep track of addresses for you, + so you can work with meaningful names instead of "magic" + numbers. +

This can be done in a number of ways:

+
+ 
+GlobalLabel ; This syntax is deprecated,
+AnotherGlobal: ; please use this instead
+.locallabel
+.yet_a_local:
+AnotherGlobal.with_another_local:
+ThisWillBeExported:: ; Note the two colons
+ThisWillBeExported.too::
+
+
+

Declaring a label (global or local) with + ‘::’ does an + EXPORT at the same time. (See + Exporting and + importing symbols below).

+

Any label whose name does not contain a period is a global + label, others are locals. Declaring a global label sets it as the + current label scope until the next one; any local label whose first + character is a period will have the global label's name implicitly + prepended. Local labels can be declared as + ‘scope.local:’ or simply as as + ‘.local:’. If the former notation + is used, then ‘scope’ must be the + actual current scope.

+

A label's location (and thus value) is usually not determined + until the linking stage, so labels usually cannot be used as constants. + However, if the section in which the label is declared has a fixed base + address, its value is known at assembly time.

+

rgbasm is able to compute the + subtraction of two labels either if both are constant as described + above, or if both belong to the same section.

+
+
+
+ allows defining constant symbols. Unlike SET + below, constants defined this way cannot be redefined. They can, for + example, be used for things such as bit definitions of hardware registers. +
+ 
+SCREEN_WIDTH   equ 160 ; In pixels
+SCREEN_HEIGHT  equ 144
+
+
+

Note that colons ‘:’ + following the name are not allowed.

+
+
+
, + or its synonym =, defines constant symbols like + EQU, but those constants can be re-defined. This + is useful for variables in macros, for counters, etc. +
+ 
+ARRAY_SIZE EQU 4
+COUNT      SET 2
+COUNT      SET ARRAY_SIZE+COUNT
+; COUNT now has the value 6
+COUNT      = COUNT + 1
+
+
+

Note that colons ‘:’ + following the name are not allowed.

+
+
, + 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 constants as if by:

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

There are five commands in the RS group of commands:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
CommandMeaning
Equivalent to ‘RSSET 0’.
+ constexprSets the _RS counter + to constexpr.
+ constexprSets the preceding symbol to _RS + and adds constexpr + to _RS.
+ constexprSets the preceding symbol to _RS + and adds constexpr + * 2 to _RS.
+ constexprSets the preceding symbol to _RS + and adds constexpr + * 4 to _RS. (In + practice, this one cannot be used due to a bug).
+

Note that colons ‘:’ + following the name are not allowed.

+
+
+
+ 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 similar to #define . +
+ 
+COUNTREG EQUS "[hl+]"
+    ld a,COUNTREG
+
+PLAYER_NAME EQUS "\"John\""
+    db PLAYER_NAME
+
+
+

This will be interpreted as:

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

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 colons ‘:’ + following the name are 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. If + this creates an infinite loop, rgbasm will error + out once a certain depth is reached. See the -r + command-line option in rgbasm(1). Also, a macro can + contain an EQUS which calls the same macro, + which causes the same problem.

+
+
+
One of the best features of an assembler is the ability to write macros + for it. Macros can be called with arguments, and can react depending on + input using IF constructs. +
+ 
+MyMacro: MACRO
+         ld   a,80
+         call MyFunc
+         ENDM
+
+
+

Note that a single colon + ‘:’ following the macro's name is + required. Macros can't be exported or imported.

+
+
+
+

+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 rgbasm finds a symbol it does not + know about.

+

The following will cause symbol1, + symbol2 and so on to be accessible to other files + during the link process:

+
EXPORT + symbol1 [, symbol2, + ...]
+

GLOBAL is a deprecated synonym for + EXPORT, do not use it.

+

Note also that only exported symbols will appear in symbol and map + files produced by rgblink(1).

+
+
+

+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 a symbol that you use in expressions + the linker needs to calculate. When not sure, it's probably not safe to purge + anything other than string symbols, macros, and constants. +
+
+Kamikaze EQUS  "I don't want to live anymore"
+AOLer    EQUS  "Me too"
+         PURGE Kamikaze, AOLer
+
+
+

Note that, as an exception, string symbols in the argument list of + a PURGE command will not be + expanded.

+
+
+

+The following symbols are defined by the assembler: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameContents
PC value
Fixed point π
_RS Counter
Number of arguments passed to macro
The current line number
The current filename
Today's date
The current time
ISO 8601 timestamp (local)
ISO 8601 timestamp (UTC)
Today's year
Today's month number, 1–12
Today's day of the month, 1–31
Current hour, 0–23
Current minute, 0–59
Current second, 0–59
Major version number of RGBDS
Minor version number of RGBDS
Patch version number of RGBDS
+
+
+
+

+
+

+DS allocates a number of empty bytes. This is the + preferred method of allocating space in a RAM section. You can also use + DB, DW and + DL without any arguments instead (see + Defining constant data + below). +
+
+DS 42 ; Allocates 42 bytes
+
+
+

Empty space in RAM sections will not be initialized. In ROM + sections, it will be filled with the value passed to the + -p command-line option, except when using overlays + with -O.

+
+
+

+DB defines a list of bytes that will be stored in the + final image. Ideal for tables and text. Note that strings are not + zero-terminated! +
+
+DB 1,2,3,4,"This is a string"
+
+
+

DS can also be used to fill a region of + memory with some value. The following produces 42 times the byte $FF:

+
+
+DS 42, $FF
+
+
+

Alternatively, you can use DW to store a + list of words (16-bit) or DL to store a list of + double-words/longs (32-bit). 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, no-argument + DB, DW and + DL can be used in a WRAM0 / + WRAMX / HRAM / + VRAM / SRAM section.

+
+
+

+You probably have some graphics, level data, etc. 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 + rgbasm(1) (see the -i option) on the + command line will be searched. +
+
+INCBIN "titlepic.bin"
+INCBIN "sprites/hero.bin"
+
+
+

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 allow multiple memory allocations to overlap, like unions in C. This does + not increase the amount of memory available, but allows re-using the same + memory region for different purposes. +

A union starts with a UNION keyword, and + ends at the corresponding ENDU keyword. + NEXTU separates each block of allocations, and you + may use it as many times within a union as necessary.

+
+
+    ; Let's say PC = $C0DE here
+    UNION
+    ; Here, PC = $C0DE
+Name: ds 8
+    ; PC = $C0E6
+Nickname: ds 8
+    ; PC = $C0EE
+    NEXTU
+    ; PC is back to $C0DE
+Health: dw
+    ; PC = $C0E0
+Something: ds 6
+    ; And so on
+Lives: db
+    NEXTU
+VideoBuffer: ds 19
+    ENDU
+
+
+

In the example above, ‘Name, Health, VideoBuffer’ + all have the same value, as do ‘Nickname’ and + ‘Lives’. Thus, keep in mind that ld [Health], + a is identical to ld [Name], a.

+

The size of this union is 19 bytes, as this is the size of the + largest block (the last one, containing ‘VideoBuffer’). + Nesting unions is possible, with each inner union's size being considered as + described above.

+

Unions may be used in any section, but inside them may only be + DS - like commands (see + Declaring + variables in a RAM section).

+
+
+
+

+
+

+You execute the macro by inserting its name. +
+
+         add a,b
+         ld sp,hl
+         MyMacro ; This will be expanded
+         sub a,87
+
+
+

It's valid to call a macro from a macro (yes, even the same + one).

+

When rgbasm sees + MyMacro it will insert the macro definition (the + code 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, but only if you use the macro no more than once per + scope. To get around this problem, there is the escape sequence + \@ that expands to a unique string.

+

\@ also works in + REPT blocks.

+
+
+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 circular + dependency problems. If this creates an infinite loop, + rgbasm will error out once a certain depth is + reached. See the -r command-line option in + rgbasm(1). Also, a macro can have inside an + EQUS which references the same macro, which has the same + problem.

+

It's possible to pass arguments to macros as well! You retrieve + the arguments by using the escape sequences \1 + through \9, \1 being the + first argument specified on the macro invocation.

+
+
+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 byte count. The generated code will then + reset all bytes in this range.

+
+
+LoopyMacro MyVars,54
+
+
+

Arguments are passed as string equates, although there's no need + to enclose them in quotes. Thus, an expression will not be evaluated first + but kind of copy-pasted. 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, consider the + following:

+
+
+print_double: MACRO
+    PRINTV \1 * 2
+ENDM
+    print_double 1 + 2
+
+
+

The PRINTV statement will expand to + ‘PRINTV 1 + 2 * 2’, which will print 5 + and not 6 as you might have expected.

+

Line continuations work as usual inside macros or lists of macro + arguments. However, some characters need to be escaped, as in the following + example:

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

The comma needs to be escaped to avoid it being treated as + separating the macro's arguments. The backslash ‘\’ (from + ‘\n’) also needs to be escaped because of the way + rgbasm processes macro arguments.

+

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 SHIFT command.

+

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 of \3, and so forth.

+

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

+

SHIFT can optionally be given an integer + parameter, and will apply the above shifting that number of times.

+
+
+

+The next four commands print text and values to the standard output. 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
+PRINTF MUL(3.14, 3987.0)
+
+
+
+
+
prints out a string. Be careful to add a line feed (“\n”) at + the end, as it is not added automatically.
+
+
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 + symbol's value.
+
+
prints out a signed integer value.
+
+
prints out a fixed point value.
+
+

Be careful that none of those automatically print a line feed; if + you need one, use PRINTT \n.

+
+
+

+Suppose you want to unroll a time consuming loop without copy-pasting it. + REPT is here for that purpose. Everything between + REPT and the matching ENDR + will be repeated a number of times just as if you had 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 =   0.0
+      REPT  256
+      db    (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
+ANGLE = ANGLE+256.0
+      ENDR
+
+
+

As in macros, you can also use the escape sequence + \@. 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.

+

If you need to ensure some assumption is correct when compiling, + you can use ASSERT and + STATIC_ASSERT. Syntax examples are given below:

+
+
+Function:
+      xor a
+ASSERT LOW(Variable) == 0
+      ld h, HIGH(Variable)
+      ld l, a
+      ld a, [hli]
+      ; You can also indent this!
+      ASSERT BANK(OtherFunction) == BANK(Function)
+      call OtherFunction
+; Lowercase also works
+assert Variable + 1 == OtherVariable
+      ld c, [hl]
+      ret
+.end
+      ; If you specify one, a message will be printed
+      STATIC_ASSERT .end - Function < 256, "Function is too large!"
+
+
+

First, the difference between ASSERT and + STATIC_ASSERT is that the former is evaluated by + RGBASM if it can, otherwise by RGBLINK; but the latter is only ever + evaluated by RGBASM. If RGBASM cannot compute the value of the argument to + STATIC_ASSERT, it will produce an error.

+

Second, as shown above, a string can be optionally added at the + end, to give insight into what the assertion is checking.

+

Finally, you can add one of WARN, + FAIL or FATAL as the first + optional argument to either ASSERT or + STATIC_ASSERT. If the assertion fails, + WARN will cause a simple warning (controlled by + rgbasm(1) flag -Wassert) to be + emitted; FAIL (the default) will cause a non-fatal + error; and FATAL immediately aborts.

+
+
+

+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 (see the -i option in + rgbasm(1)) will be searched. You may nest + INCLUDE calls infinitely (or until you run out of + memory, whichever comes first). +
+
+    INCLUDE "irq.inc"
+
+
+
+
+

+The four commands IF, ELIF, + ELSE, and ENDC let you have + rgbasm skip over parts of your code depending on a + condition. 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 (standing for "else + if") 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.

+
+
+

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 + assembling from within the source, instead of defining them on the + command-line. +

OPT takes a comma-separated list of options as its argument:

@@ -1394,13 +1654,14 @@ DW    `00112233

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

+ b, g and + p.

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 + destroy the options set by the program that included your file. The stack's number of entries is limited only by the amount of memory in your machine.

@@ -1408,13 +1669,13 @@ DW `00112233

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

-rgbds was originally written by Carsten Sørensen +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. @@ -1422,8 +1683,8 @@ DW `00112233 - - + +
March 13, 2018RGBDS ManualDecember 5, 2019General
diff --git a/docs/rgbds.5.html b/docs/rgbds.5.html index fc0e5156..ae3beea9 100644 --- a/docs/rgbds.5.html +++ b/docs/rgbds.5.html @@ -8,8 +8,10 @@ SPDX-License-Identifier: MIT --> + + RGBDS(5) @@ -24,29 +26,30 @@

rgbds — -
object file format documentation
+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. +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.

+ little‐endian format. BYTE is an 8‐bit + integer. STRING is a 0‐terminated string of + BYTE.

 ; Header
 
-BYTE    ID[4]            ; "RGB6"
+BYTE    ID[4]            ; "RGB9"
+LONG    RevisionNumber   ; The format's revision number this file uses
 LONG    NumberOfSymbols  ; The number of symbols used in this file
 LONG    NumberOfSections ; The number of sections used in this file
 
@@ -60,8 +63,10 @@ REPT    NumberOfSymbols   ; Number of symbols defined in this object file.
     BYTE    Type          ; 0 = LOCAL symbol only used in this file.
                           ; 1 = IMPORT this symbol from elsewhere
                           ; 2 = EXPORT this symbol to other objects.
+                          ; Bit 7 is independent from the above value, and
+                          ; encodes whether the section is unionized
 
-    IF      Type != 1     ; If symbol is defined in this object file.
+    IF (Type & 0x7F) != 1 ; If symbol is defined in this object file.
 
         STRING  FileName  ; File where the symbol is defined.
 
@@ -102,8 +107,8 @@ REPT NumberOfSections
                   ; 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.
+    LONG    Align ; Alignment of this section, expressed as 1 << align. 1 if
+                  ; not specified.
 
     IF      (Type == ROMX) || (Type == ROM0) ; Sections that can contain data.
 
@@ -118,8 +123,6 @@ REPT NumberOfSections
             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).
 
@@ -137,6 +140,34 @@ REPT NumberOfSections
 
     ENDC
 
+ENDR
+
+; Assertions
+
+LONG  NumberOfAssertions
+
+REPT  NumberOfAssertions
+
+  STRING  SourceFile   ; Name of the source file (for printing the failure).
+
+  LONG    Offset       ; Offset into the section where the assertion is located.
+
+  BYTE    Type         ; 0 = Prints the message but allows linking to continue
+                       ; 1 = Prints the message and evaluates other assertions,
+                       ;     but linking fails afterwards
+                       ; 2 = Prints the message and immediately fails linking
+
+  LONG    RPNSize      ; Size of the RPN expression's buffer.
+
+  BYTE    RPN[RPNSize] ; RPN expression, same as patches. Assert fails if == 0.
+
+  LONG    SectionID    ; The section number (of this object file) in which this
+                       ; assert is defined. If it doesn't belong to any specific
+                       ; section (like a constant), this field has the value -1.
+
+  STRING  Message      ; A message displayed when the assert fails. If set to
+                       ; the empty string, a generic message is printed instead.
+
 ENDR
@@ -145,15 +176,15 @@ ENDR DATA 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” - to the stack. Then “5”. The “+” operator pops two + to the stack, then “5”. The “+” operator pops two arguments from the stack, adds them, and then pushes the result on the stack, 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. + RPN expressions are stored as BYTEs with some bytes + being special prefixes for integers and symbols. - - + + @@ -261,23 +292,28 @@ Expressions in the object file are stored as RPN. This is an expression of the - - + BANK() - + + + + + @@ -285,7 +321,7 @@ Expressions in the object file are stored as RPN. This is an expression of the - +
ValueMeaningValueMeaning
+ , a LONG Symbol ID follows.
+ , a null-terminated string follows.
.
- Check if the value is in HRAM, AND it with 0xFF.. + Checks if the value is in HRAM, ANDs it with 0xFF.
. + Checks if the value is a RST vector, ORs it with 0xC7.
LONG Symbol ID follows.LONG symbol ID follows.
@@ -293,8 +329,8 @@ Expressions in the object file are stored as RPN. This is an expression of the

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

@@ -307,7 +343,7 @@ Expressions in the object file are stored as RPN. This is an expression of the - +
January 26, 2018RGBDS ManualGeneral
diff --git a/docs/rgbds.7.html b/docs/rgbds.7.html index 2f0ed658..01872533 100644 --- a/docs/rgbds.7.html +++ b/docs/rgbds.7.html @@ -8,8 +8,10 @@ SPDX-License-Identifier: MIT --> + + RGBDS(7) @@ -24,7 +26,7 @@

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

@@ -40,9 +42,9 @@ $ rgbfix -v -p 0 baz.gb

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

@@ -71,7 +73,7 @@ $ rgbfix -v -p 0 baz.gb - +
March 7, 2018RGBDS ManualGeneral
diff --git a/docs/rgbfix.1.html b/docs/rgbfix.1.html index 4d4dbfee..67cc4030 100644 --- a/docs/rgbfix.1.html +++ b/docs/rgbfix.1.html @@ -8,8 +8,10 @@ SPDX-License-Identifier: MIT --> + + RGBFIX(1) @@ -24,22 +26,23 @@

rgbfix — -
Game Boy checksum fixer
+Game Boy header utility and 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 + [-jsVv] [-C | + -c] [-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
@@ -47,19 +50,28 @@

The rgbfix program changes headers of Game Boy ROM - images. It also performs other filetype operations, such as truncation. The - arguments are as follows: + images. It also performs other correctness operations, such as padding. +

Note that options can be abbreviated as long as the abbreviation + is unambiguous: --verb is + --verbose, but + --ver is invalid because it + could also be --version. The + arguments are as follows:

-
+
, + --color-only
Set the Game Boy Color–only flag: 0x143 = 0xC0. If both this and the -c flag are set, this takes precedence.
-
+
, + --color-compatible
Set the Game Boy Color–compatible flag: 0x143 = 0x80. If both this and the -C flag are set, -C takes precedence.
+ fix_spec, + --fix-spec fix_spec
Fix certain header values that the Game Boy checks for correctness. Alternatively, intentionally trash these values by writing their binary @@ -84,45 +96,64 @@ The rgbfix program changes headers of Game Boy ROM
+ game_id, + --game-id 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.
-
+
, + --non-japanese
Set the non-Japanese region flag: 0x14A = 1.
+ licensee_str, + --new-licensee licensee_str
Set the new licensee string (0x144–0x145) to a given string, truncated to at most two characters.
+ licensee_id, + --old-licensee 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, + --mbc-type mbc_type
Set the MBC type, 0x147, to a given value from 0 to 0xFF.
+ rom_version, + --rom-version rom_version
Set the ROM version, 0x14C, to a given value from 0 to 0xFF.
+ pad_value, + --pad-value 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.
+ rgbfix will automatically pick a size from 32 KiB, + 64 KiB, 128 KiB, ..., 8192 KiB. The cartridge size byte + (0x148) will be changed to reflect this new + size.
+ ram_size, + --ram-size ram_size
Set the RAM size, 0x149, to a given value from 0 to 0xFF.
-
-
Set the SGB flag: 0x146 = 3.
+
, + --sgb-compatible
+
Set the SGB flag: 0x146 = 3. This flag will be + ignored by the SGB unless the old licensee code is 0x33!
+ title, + --title title
Set the title string (0x134–0x143) to a @@ -131,28 +162,29 @@ The rgbfix program changes headers of Game Boy ROM (-c or -C). If both this and the game ID are set, the game ID will overwrite the overlapping portion of the title.
-
+
, + --version
Print the version of the program and exit.
-
+
, + --validate
Equivalent to -f lhg.

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 + for a workable program are the header checksum, 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 power of 2, times 32 KiB). +

The following will make a plain, non-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.)

+ title of “foobar”, and pad it to a valid size. (The Game Boy + itself does not use the title, but some emulators or ROM managers do.)

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

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

@@ -160,10 +192,15 @@ Most values in the ROM header are only cosmetic. The bare minimum requirements SURVIVALKIDAVKE SurvivalKids.gbc
+

+Please report bugs on + GitHub. +
+

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

@@ -175,8 +212,8 @@ Most values in the ROM header are only cosmetic. The bare minimum requirements - - + +
March 11, 2018RGBDS ManualDecember 5, 2019General
diff --git a/docs/rgbgfx.1.html b/docs/rgbgfx.1.html index 088167af..13d67c2e 100644 --- a/docs/rgbgfx.1.html +++ b/docs/rgbgfx.1.html @@ -8,8 +8,10 @@ SPDX-License-Identifier: MIT --> + + RGBGFX(1) @@ -24,20 +26,23 @@

rgbgfx — -
Game Boy graphics converter
+Game Boy graphics converter

- +
rgbgfx[-ADfFhmPTuVv] [-o - outfile] [-a - attrmap] [-d - depth] [-p - palfile] [-t - tilemap] [-x - tiles] file[-CDhmuVv] [-f | + -F] [-a + attrmap | -A] + [-d depth] + [-o out_file] + [-p pal_file | + -P] [-t + tilemap | -T] + [-x tiles] + file
@@ -54,9 +59,9 @@ The rgbgfx program converts PNG images into the Nintendo the indices appropriate for each shade. Any undetermined indices are set to respective default shades of gray. For example: if the bit depth is 2 and the image contains light gray and black, they become the second and - fourth colors - and the first and third colors get set to default white - and dark gray. If the image has multiple shades that map to the same - index, the palette is instead determined as if the image had color. + fourth colors, and the first and third colors get set to default white and + dark gray. If the image has multiple shades that map to the same index, + the palette is instead determined as if the image had color.
  • If the image has color (or the grayscale method failed), the colors are sorted from lightest to darkest.
    • @@ -65,73 +70,103 @@ The rgbgfx program converts PNG images into the Nintendo

    +Note that options can be abbreviated as long as the abbreviation is unambiguous: + --verb is + - -verbose, but + --ver is invalid because it + could also be --version. The + arguments are as follows:
    + attrmap, + --attr-map 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.
    -
    +
    , + --output-attr-map
    Same as -a, but the attrmap file output name is made by taking the input filename, removing the file extension, and appending .attrmap.
    -
    +
    , + --color-curve
    Use the color curve of the Game Boy Color when generating palettes.
    -
    +
    , + --debug
    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, + --depth depth
    The bit depth of the output image (either 1 or 2). By default, the bit depth is 2 (two bits per pixel).
    -
    +
    , + --fix
    +
    Fix the input PNG file to be a correctly indexed image.
    +
    , + --fix-and-save
    +
    Same as -f, but additionally, the supplied command + line parameters are saved within the PNG and will be loaded and + automatically used next time.
    +
    , + --horizontal
    Lay out tiles horizontally rather than vertically.
    -
    +
    , + --mirror-tiles
    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
    + out_file, + --output + out_file
    The name of the output file.
    - palfile
    -
    Output the image's palette in standard GBC palette format - bytes (8 bytes + pal_file, + --palette + pal_file +
    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.
    -
    +
    , + --output-palette
    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, + --tilemap 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.
    -
    +
    , + --output-tilemap
    Same as -t, but the tilemap file output name is made by taking the input filename, removing the file extension, and appending .tilemap.
    -
    +
    , + --unique-tiles
    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.
    -
    +
    , + --version
    Print the version of the program and exit.
    -
    +
    , + --verbose
    Verbose. Print errors when the command line parameters and the parameters in the PNG file don't match.
    + tiles, + --trim-end tiles
    Trim the end of the output file by this many tiles.
    @@ -147,8 +182,8 @@ The following will take a PNG file with a bit depth of 1, 2, or 8, and output

    $ 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 + accounting for tile mirroring and its associated + tilemap out.tilemap and attrmap out.attrmap:

    $ rgbgfx -A -T -m -o out.2bpp in.png
    @@ -157,11 +192,16 @@ The following will take a PNG file with a bit depth of 1, 2, or 8, and output
    $ rgbgfx in.png
    +

    +Please report bugs on + GitHub. +
    +

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

    @@ -172,8 +212,8 @@ The following will take a PNG file with a bit depth of 1, 2, or 8, and output - - + +
    January 26, 2018RGBDS ManualDecember 5, 2019General
    diff --git a/docs/rgblink.1.html b/docs/rgblink.1.html index 1761f727..42b4ca8b 100644 --- a/docs/rgblink.1.html +++ b/docs/rgblink.1.html @@ -3,13 +3,15 @@ + + RGBLINK(1) @@ -24,81 +26,114 @@

    rgblink — -
    Game Boy linker
    +Game Boy linker

    - +
    rgblink[-dtVw] [-m - mapfile] [-n - symfile] [-O - overlayfile] [-o - outfile] [-p - pad_value] [-s - symbol] [-l - linkerscript] file ...[-dtVvw] [-l + linker_script] [-m + map_file] [-n + sym_file] [-O + overlay_file] [-o + out_file] [-p + pad_value] [-s + symbol] file ...

    -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 RGB object files, typically + created by rgbasm(1), into a single Game Boy ROM file. The + format is documented in rgbds(5). +

    ROM0 sections are placed in the first 16 KiB of the output ROM, + and ROMX sections are placed in any 16 KiB “bank” except the + first. If your ROM will only be 32 KiB, you can use the + -t option to change this.

    +

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

    +

    Also, if your ROM is designed for a monochrome Game Boy, you can + make sure that you don't use any incompatible section by using the + -d option, which implies -w + but also prohibits the use of banked VRAM.

    +

    Note that options can be abbreviated as long as the abbreviation + is unambiguous: --verb is + --verbose, but + --ver is invalid because it + could also be --version. The + arguments are as follows:

    -
    - 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.
    -
    +
    , + --dmg
    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.
    -
    + linker_script, + --linkerscript + linker_script +
    Specify a linker script file that tells the linker how sections must be + placed in the ROM. The attributes assigned in the linker script must be + consistent with any assigned in the code. See rgblink(5) + for more information about the linker script format.
    +
    + map_file, + --map + map_file
    +
    Write a map file to the given filename, listing how sections and symbols + were assigned.
    +
    + sym_file, + --sym + sym_file
    +
    Write a symbol file to the given filename, listing the address of all + exported symbols. Several external programs can use this information, for + example to help debugging ROMs.
    +
    + overlay_file, + --overlay + overlay_file
    +
    If specified, sections will be overlaid "on top" of the provided + ROM image. In that case, all sections must be fixed. This may be used to + patch an existing binary.
    +
    + out_file, + --output + out_file
    +
    Write the ROM image to the given file.
    +
    + pad_value, + --pad + pad_value
    +
    When inserting padding between sections, pad with this value. Has no + effect if -O is specified. The default is 0.
    +
    + symbol, + --smart + symbol
    +
    This option is ignored. It was supposed to perform smart linking but fell + into disrepair, and so has been removed. It will be reimplemented at some + point.
    +
    , + --tiny
    +
    Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to + ROM and prohibit the use of ROMX sections. Useful for ROMs that fit in 32 + KiB.
    +
    , + --version
    Print the version of the program and exit.
    +
    , + --verbose
    +
    Verbose: enable printing more information to standard error.
    +
    , + --wramx
    +
    Expand the WRAM0 section size from 4 KiB to the full 8 KiB assigned to + WRAM and prohibit the use of WRAMX sections.
    @@ -107,18 +142,28 @@ 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:

    +

    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
    +
    $ rgbfix -v bar.gb
    +

    Here is a more complete example:

    +

    +
    $ rgblink -o bin/game.gb -n + bin/game.sym -p 0xFF obj/title.o obj/engine.o
    +
    +
    +

    +Please report bugs on + GitHub.

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

    @@ -130,8 +175,8 @@ All you need for a basic ROM is an object file, which can be made into a ROM - - + +
    January 26, 2018RGBDS ManualNovember 26, 2019General
    diff --git a/docs/rgblink.5.html b/docs/rgblink.5.html index 18624050..90aa4756 100644 --- a/docs/rgblink.5.html +++ b/docs/rgblink.5.html @@ -8,8 +8,10 @@ SPDX-License-Identifier: MIT --> + + RGBLINK(5) @@ -24,17 +26,15 @@

    rgblink — -
    linkerscript file format
    +linker script 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 +The linker script is an external file that allows the user to specify the order + of sections at link time and in a centralized manner. +

    A linker script 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:

    @@ -50,42 +50,48 @@ WRAMX 2

    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 + name or command is 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.

    +

    The possible bank types are: ROM0, + ROMX, VRAM, + SRAM, WRAM0, + WRAMX, OAM and + HRAM. Unless there is a single bank, which can occur + with types ROMX, VRAM, + SRAM and WRAMX, it is needed + to specify a bank number 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:

    + be placed right from the beginning of that bank. If the linker script + switches to a different bank and then comes back to a 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).
      • +
    • + sets the address in which new sections will be placed. It can not be lower + than the current address.
      • +
    • + 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.

    +

    Note: The bank, alignment, address and type of + sections can be specified both in the source code and in the linker script. + For a section to be able to be placed with the linker script, the bank, + address and alignment must be left unassigned in the source code or be + compatible with what is specified in the linker script. For example, + ‘ALIGN[8]’ in the source code is + compatible with ‘ORG $F00’ in the + linker script.

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

    @@ -97,8 +103,8 @@ WRAMX 2 - - + +
    January 27, 2018RGBDS ManualNovember 26, 2019General