From 292302c6d127f9aa6e8e443b4d41077d9ce00063 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antonio=20Ni=C3=B1o=20D=C3=ADaz?= Date: Tue, 23 Jan 2018 21:28:10 +0000 Subject: [PATCH] Move documentation to this repository MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Modified Makefile wwwman target to output files inside docs/. Modified .gitignore to allow *.html files. Update README. Signed-off-by: Antonio Niño Díaz --- .gitignore | 1 - Makefile | 18 +- README.rst | 7 +- docs/gbds.7.html | 65 ++ docs/gbz80.7.html | 1697 +++++++++++++++++++++++++++++++++++++++++++ docs/index.html | 32 + docs/rgbasm.1.html | 146 ++++ docs/rgbasm.5.html | 1459 +++++++++++++++++++++++++++++++++++++ docs/rgbds.5.html | 306 ++++++++ docs/rgbfix.1.html | 187 +++++ docs/rgbgfx.1.html | 153 ++++ docs/rgblink.1.html | 161 ++++ docs/rgblink.5.html | 105 +++ 13 files changed, 4323 insertions(+), 14 deletions(-) create mode 100644 docs/gbds.7.html create mode 100644 docs/gbz80.7.html create mode 100644 docs/index.html create mode 100644 docs/rgbasm.1.html create mode 100644 docs/rgbasm.5.html create mode 100644 docs/rgbds.5.html create mode 100644 docs/rgbfix.1.html create mode 100644 docs/rgbgfx.1.html create mode 100644 docs/rgblink.1.html create mode 100644 docs/rgblink.5.html diff --git a/.gitignore b/.gitignore index 70b34dbf..e8ae0a23 100644 --- a/.gitignore +++ b/.gitignore @@ -4,5 +4,4 @@ rgbfix rgbgfx *.o *.exe -*.html .checkpatch-camelcase.* diff --git a/Makefile b/Makefile index d2126cb7..f228ed08 100644 --- a/Makefile +++ b/Makefile @@ -169,15 +169,15 @@ checkpatch: MANDOC := -Thtml -Ios=General -Oman=%N.%S.html -Ostyle=manual.css wwwman: - $Qmandoc ${MANDOC} src/rgbds.7 > rgbds.7.html - $Qmandoc ${MANDOC} src/gbz80.7 > gbz80.7.html - $Qmandoc ${MANDOC} src/rgbds.5 > rgbds.5.html - $Qmandoc ${MANDOC} src/asm/rgbasm.1 > rgbasm.1.html - $Qmandoc ${MANDOC} src/asm/rgbasm.5 > rgbasm.5.html - $Qmandoc ${MANDOC} src/fix/rgbfix.1 > rgbfix.1.html - $Qmandoc ${MANDOC} src/link/rgblink.1 > rgblink.1.html - $Qmandoc ${MANDOC} src/link/rgblink.5 > rgblink.5.html - $Qmandoc ${MANDOC} src/gfx/rgbgfx.1 > rgbgfx.1.html + $Qmandoc ${MANDOC} src/rgbds.7 > docs/gbds.7.html + $Qmandoc ${MANDOC} src/gbz80.7 > docs/gbz80.7.html + $Qmandoc ${MANDOC} src/rgbds.5 > docs/rgbds.5.html + $Qmandoc ${MANDOC} src/asm/rgbasm.1 > docs/rgbasm.1.html + $Qmandoc ${MANDOC} src/asm/rgbasm.5 > docs/rgbasm.5.html + $Qmandoc ${MANDOC} src/fix/rgbfix.1 > docs/rgbfix.1.html + $Qmandoc ${MANDOC} src/link/rgblink.1 > docs/rgblink.1.html + $Qmandoc ${MANDOC} src/link/rgblink.5 > docs/rgblink.5.html + $Qmandoc ${MANDOC} src/gfx/rgbgfx.1 > docs/rgbgfx.1.html # Targets for the project maintainer to easily create Windows exes. # This is not for Windows users! diff --git a/README.rst b/README.rst index a23cd566..c7886806 100644 --- a/README.rst +++ b/README.rst @@ -12,12 +12,11 @@ for the Game Boy and Game Boy Color. It consists of: This is a fork of the original RGBDS which aims to make the programs more like other UNIX tools. -This toolchain is maintained on `GitHub `__, as -well as its `documentation `__. +This toolchain is maintained on `GitHub `__. The documentation of this toolchain can be viewed online -`here `__, it is generated from the man pages found -in this repository. +`here `__, it is generated from the man pages +found in this repository. 1. Installing RGBDS ------------------- diff --git a/docs/gbds.7.html b/docs/gbds.7.html new file mode 100644 index 00000000..35e4b0c9 --- /dev/null +++ b/docs/gbds.7.html @@ -0,0 +1,65 @@ + + + + + + + RGBDS(7) + + + + + + + + +
RGBDS(7)Miscellaneous Information ManualRGBDS(7)
+
+

NAME

+rgbds — Rednex + Game Boy Development System +

EXAMPLES

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

SEE + ALSO

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

HISTORY

+
+
+
1997, Carsten Sørensen (AKA SurfSmurf) writes + ASMotor as a general-purpose assembler/linker system for DOS/Win32.
+
+
1999, Justin Lloyd (AKA Otaku no Zoku) adapts ASMotor to + read and produce GBZ80 assembly/machine code, and releases this version as + RGBDS.
+
+
2009, Vegard Nossum adapts the code to be more UNIX-like + and releases this version as rgbds-linux on GitHub.
+
+
2010, Anthony J. Bentley forks that repository. The fork + becomes the reference implementation of rgbds.
+
+
2017, Bentley's repository is moved to a neutral name. It + is now maintained by a number of contributors at + https://github.com/rednex/rgbds.
+
+
+ + + + + +
April 17, 2017RGBDS Manual
+ + diff --git a/docs/gbz80.7.html b/docs/gbz80.7.html new file mode 100644 index 00000000..3947d694 --- /dev/null +++ b/docs/gbz80.7.html @@ -0,0 +1,1697 @@ + + + + + + + GBZ80(7) + + + + + + + + +
GBZ80(7)Miscellaneous Information ManualGBZ80(7)
+
+

NAME

+gbz80 — CPU + opcode reference +

DESCRIPTION

+This is the list of opcodes supported by rgbasm(1), + including a short description, the number of bytes needed to encode them and + the number of CPU cycles at 1MHz (or 2MHz in GBC dual speed mode) needed to + complete them. +
+Note: All arithmetic/logic operations that use register + A as destination can omit the destination as it + is assumed it's register A. The following two + lines have the same effect: +
+
OR A,B
+
OR B
+

LEGEND

+List of abbreviations used in this document. +
+
 
+
 
+
r8
+
Any of the 8-bit registers (A, + B, C, + D, E, + H, L).
+
 
+
 
+
r16
+
Any of the general-purpose 16-bit registers + (BC, DE, + HL).
+
 
+
 
+
n8
+
8-bit integer constant.
+
 
+
 
+
n16
+
16-bit integer constant.
+
 
+
 
+
e8
+
8-bit offset + (-128 to + 127).
+
 
+
 
+
u3
+
3-bit unsigned integer constant + (0 to 7).
+
 
+
 
+
cc
+
Condition codes: +
+
Z:
+
Execute if Z is set.
+
NZ:
+
Execute if Z is not set.
+
C:
+
Execute if C is set.
+
NC:
+
Execute if C is not set.
+
+
+
 
+
 
+
vec
+
One of the RST vectors + (0x00, 0x08, + 0x10, 0x18, + 0x20, 0x28, + 0x30 and + 0x38).
+
+

INSTRUCTION + OVERVIEW

+

8-bit + Arithmetic and Logic Instructions

+
+
ADC + A,r8
+
+
ADC + A,[HL]
+
+
ADC + A,n8
+
+
ADD + A,r8
+
+
ADD + A,[HL]
+
+
ADD + A,n8
+
+
AND + A,r8
+
+
AND + A,[HL]
+
+
AND + A,n8
+
+
CP A,r8
+
+
CP + A,[HL]
+
+
CP A,n8
+
+
DEC r8
+
+
DEC + [HL]
+
+
INC r8
+
+
INC + [HL]
+
+
OR A,r8
+
+
OR + A,[HL]
+
+
OR A,n8
+
+
SBC + A,r8
+
+
SBC + A,[HL]
+
+
SBC + A,n8
+
+
SUB + A,r8
+
+
SUB + A,[HL]
+
+
SUB + A,n8
+
+
XOR + A,r8
+
+
XOR + A,[HL]
+
+
XOR + A,n8
+
+
+

16-bit + Arithmetic Instructions

+
+
ADD + HL,r16
+
+
DEC r16
+
+
INC r16
+
+
+

Bit + Operations Instructions

+
+
BIT + u3,r8
+
+
BIT + u3,[HL]
+
+
RES + u3,r8
+
+
RES + u3,[HL]
+
+
SET + u3,r8
+
+
SET + u3,[HL]
+
+
SWAP r8
+
+
SWAP + [HL]
+
+
+

Bit + Shift Instructions

+
+
RL r8
+
+
RL [HL]
+
+
RLA
+
+
RLC r8
+
+
RLC + [HL]
+
+
RLCA
+
+
RR r8
+
+
RR [HL]
+
+
RRA
+
+
RRC r8
+
+
RRC + [HL]
+
+
RRCA
+
+
SLA r8
+
+
SLA + [HL]
+
+
SRA r8
+
+
SRA + [HL]
+
+
SRL r8
+
+
SRL + [HL]
+
+
+

Load + Instructions

+
+
LD + r8,r8
+
+
LD + r8,n8
+
+
LD + r16,n16
+
+
LD + [HL],r8
+
+
LD + [HL],n8
+
+
LD + r8,[HL]
+
+
LD + [r16],A
+
+
LD + [n16],A
+
+
LD + [$FF00+n8],A
+
+
LD + [$FF00+C],A
+
+
LD + A,[r16]
+
+
LD + A,[n16]
+
+
LD + A,[$FF00+n8]
+
+
LD + A,[$FF00+C]
+
+
LD + [HL+],A
+
+
LD + [HL-],A
+
+
LD + A,[HL+]
+
+
LD + A,[HL-]
+
+
+

Jumps + and Subroutines

+
+
CALL + n16
+
+
CALL + cc,n16
+
+
JP HL
+
+
JP n16
+
+
JP + cc,n16
+
+
JR e8
+
+
JR + cc,e8
+
+
RET cc
+
+
RET
+
+
RETI
+
+
RST vec
+
+
+

Stack + Operations Instructions

+
+
ADD + HL,SP
+
+
ADD + SP,e8
+
+
DEC SP
+
+
INC SP
+
+
LD + SP,n16
+
+
LD + [n16],SP
+
+
LD + HL,SP+e8
+
+
LD + SP,HL
+
+
POP AF
+
+
POP r16
+
+
PUSH AF
+
+
PUSH + r16
+
+
+

Miscellaneous + Instructions

+
+
CCF
+
+
CPL
+
+
DAA
+
+
DI
+
+
EI
+
+
HALT
+
+
NOP
+
+
SCF
+
+
STOP
+
+
+

INSTRUCTION + REFERENCE

+

ADC + A,r8

+Add the value in r8 plus the carry flag to + A. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: Set if overflow from bit + 3.
    • +
  • C: Set if overflow from bit + 7.
    • +
+

ADC + A,[HL]

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

ADC + A,n8

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

ADD + A,r8

+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 + A,[HL]

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

ADD + A,n8

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

ADD + HL,r16

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

ADD + HL,SP

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

ADD + SP,e8

+Add the signed value e8 to + SP. +
+Cycles: 4 +
+Bytes: 2 +
+Flags: +
    +
  • Z: 0
    • +
  • N: 0
    • +
  • H: Set if overflow from bit + 3.
    • +
  • C: Set if overflow from bit + 7.
    • +
+

AND + A,r8

+Bitwise AND between the value in r8 and + A. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: 1
    • +
  • C: 0
    • +
+

AND + A,[HL]

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

AND + A,n8

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

BIT + u3,r8

+Test bit u3 in register + r8, set the zero flag if bit not set. +
+Cycles: 2 +
+Bytes: 2 +
+Flags: +
    +
  • Z: Set if the selected bit + is 0.
    • +
  • N: 0
    • +
  • H: 1
    • +
+

BIT + u3,[HL]

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

CALL + n16

+Call address n16. +
+Cycles: 6 +
+Bytes: 3 +
+Flags: None affected. +

CALL + cc,n16

+Call address n16 if condition + cc is met. +
+Cycles: 6/3 +
+Bytes: 3 +
+Flags: None affected. +

CCF

+Complement Carry Flag. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • N: 0
    • +
  • H: 0
    • +
  • C: Complemented.
    • +
+

CP + A,r8

+Subtract the value in r8 from + A and set flags accordingly, but don't store the + result. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 1
    • +
  • H: Set if no borrow from + bit 4.
    • +
  • C: Set if no borrow (set if + r8 > + A).
    • +
+

CP + A,[HL]

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

CP + A,n8

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

CPL

+Complement accumulator (A = + ~A). +
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • N: 1
    • +
  • H: 1
    • +
+

DAA

+Decimal adjust register A 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.
    • +
+

DEC + r8

+Decrement value in register r8 by 1. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 1
    • +
  • H: Set if no borrow from + bit 4.
    • +
+

DEC + [HL]

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

DEC + r16

+Decrement value in register r16 by 1. +
+Cycles: 2 +
+Bytes: 1 +
+Flags: None affected. +

DEC + SP

+Decrement value in register SP by 1. +
+Cycles: 2 +
+Bytes: 1 +
+Flags: None affected. +

DI

+Disable Interrupts. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: None affected. +

EI

+Enable Interrupts. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: None affected. +

HALT

+Enter CPU low power mode. +
+Cycles: - +
+Bytes: 1 +
+Flags: None affected. +

INC + r8

+Increment value in register r8 by 1. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: Set if overflow from bit + 3.
    • +
+

INC + [HL]

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

INC + r16

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

INC + SP

+Increment value in register SP by 1. +
+Cycles: 2 +
+Bytes: 1 +
+Flags: None affected. +

JP + n16

+Absolute jump to address n16. +
+Cycles: 4 +
+Bytes: 3 +
+Flags: None affected. +

JP + cc,n16

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

JP + HL

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

JR + e8

+Relative jump by adding e8 to the current + address. +
+Cycles: 3 +
+Bytes: 2 +
+Flags: None affected. +

JR + cc,e8

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

LD + r8,r8

+Store value in register on the right into register on the left. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: None affected. +

LD + r8,n8

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

LD + r16,n16

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

LD + [HL],r8

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

LD + [HL],n8

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

LD + r8,[HL]

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

LD + [r16],A

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

LD + [n16],A

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

LD + [$FF00+n8],A

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

LD + [$FF00+C],A

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

LD + A,[r16]

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

LD + A,[n16]

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

LD + A,[$FF00+n8]

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

LD + A,[$FF00+C]

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

LD + [HL+],A

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

LD + [HL-],A

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

LD + A,[HL+]

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

LD + A,[HL-]

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

LD + SP,n16

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

LD + [n16],SP

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

LD + HL,SP+e8

+Add the signed value e8 to + SP and store the result in + HL. +
+Cycles: 3 +
+Bytes: 2 +
+Flags: +
    +
  • Z: 0
    • +
  • N: 0
    • +
  • H: Set if overflow from bit + 3.
    • +
  • C: Set if overflow from bit + 7.
    • +
+

LD + SP,HL

+Load register HL into register + SP. +
+Cycles: 2 +
+Bytes: 1 +
+Flags: None affected. +

NOP

+No operation. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: None affected. +

OR + A,r8

+Bitwise OR between the value in r8 and + A. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: 0
    • +
+

OR + A,[HL]

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

OR + A,n8

+Bitwise OR between the value in n8 and + A. +
+Cycles: 2 +
+Bytes: 2 +
+Flags: See OR A,r8 +

POP + AF

+Pop register AF from the stack. +
+Cycles: 3 +
+Bytes: 1 +
+Flags: None affected. +

POP + r16

+Pop register r16 from the stack. +
+Cycles: 3 +
+Bytes: 1 +
+Flags: None affected. +

PUSH + AF

+Push register AF into the stack. +
+Cycles: 4 +
+Bytes: 1 +
+Flags: None affected. +

PUSH + r16

+Push register r16 into the stack. +
+Cycles: 4 +
+Bytes: 1 +
+Flags: None affected. +

RES + u3,r8

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

RES + u3,[HL]

+Set bit u3 in the byte pointed by + HL to 0. +
+Cycles: 4 +
+Bytes: 2 +
+Flags: None affected. +

RET

+Return from subroutine. +
+Cycles: 4 +
+Bytes: 1 +
+Flags: None affected. +

RET + cc

+Return from subroutine if condition cc is met. +
+Cycles: 5/2 +
+Bytes: 1 +
+Flags: None affected. +

RETI

+Return from subroutine and enable interrupts. +
+Cycles: 4 +
+Bytes: 1 +
+Flags: None affected. +

RL + r8

+Rotate register r8 left through carry. +
+
C <- [7 <- 0] <- C
+
+Cycles: 2 +
+Bytes: 2 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: Set according to + result.
    • +
+

RL + [HL]

+Rotate value pointed by HL left through carry. +
+
C <- [7 <- 0] <- C
+
+Cycles: 4 +
+Bytes: 2 +
+Flags: See RL r8 +

RLA

+Rotate register A left through carry. +
+
C <- [7 <- 0] <- C
+
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • Z: 0
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: Set according to + result.
    • +
+

RLC + r8

+Rotate register r8 left. +
+
C <- [7 <- 0] <- [7]
+
+Cycles: 2 +
+Bytes: 2 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: Set according to + result.
    • +
+

RLC + [HL]

+Rotate value pointed by HL left. +
+
C <- [7 <- 0] <- [7]
+
+Cycles: 4 +
+Bytes: 2 +
+Flags: See RLC r8 +

RLCA

+Rotate register A left. +
+
C <- [7 <- 0] <- [7]
+
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • Z: 0
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: Set according to + result.
    • +
+

RR + r8

+Rotate register r8 right through carry. +
+
C -> [7 -> 0] -> C
+
+Cycles: 2 +
+Bytes: 2 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: Set according to + result.
    • +
+

RR + [HL]

+Rotate value pointed by HL right through carry. +
+
C -> [7 -> 0] -> C
+
+Cycles: 4 +
+Bytes: 2 +
+Flags: See RR r8 +

RRA

+Rotate register A right through carry. +
+
C -> [7 -> 0] -> C
+
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • Z: 0
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: Set according to + result.
    • +
+

RRC + r8

+Rotate register r8 right. +
+
[0] -> [7 -> 0] -> C
+
+Cycles: 2 +
+Bytes: 2 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: Set according to + result.
    • +
+

RRC + [HL]

+Rotate value pointed by HL right. +
+
[0] -> [7 -> 0] -> C
+
+Cycles: 4 +
+Bytes: 2 +
+Flags: See RRC r8 +

RRCA

+Rotate register A right. +
+
[0] -> [7 -> 0] -> C
+
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • Z: 0
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: Set according to + result.
    • +
+

RST + vec

+Call restart vector vec. +
+Cycles: 4 +
+Bytes: 1 +
+Flags: None affected. +

SBC + A,r8

+Subtract the value in r8 and the carry flag + from A. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 1
    • +
  • H: Set if no borrow from + bit 4.
    • +
  • C: Set if no borrow (set if + r8 > + A).
    • +
+

SBC + A,[HL]

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

SBC + A,n8

+Subtract the value n8 and the carry flag from + A. +
+Cycles: 2 +
+Bytes: 2 +
+Flags: See SBC A,r8 +

SCF

+Set Carry Flag. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • N: 0
    • +
  • H: 0
    • +
  • C: 1
    • +
+

SET + u3,r8

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

SET + u3,[HL]

+Set bit u3 in the byte pointed by + HL to 1. +
+Cycles: 4 +
+Bytes: 2 +
+Flags: None affected. +

SLA + r8

+Shift left arithmetic register r8. +
+
C <- [7 <- 0] <- 0
+
+Cycles: 2 +
+Bytes: 2 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: Set according to + result.
    • +
+

SLA + [HL]

+Shift left arithmetic value pointed by HL. +
+
C <- [7 <- 0] <- 0
+
+Cycles: 4 +
+Bytes: 2 +
+Flags: See SLA r8 +

SRA + r8

+Shift right arithmetic register r8. +
+
[7] -> [7 -> 0] -> C
+
+Cycles: 2 +
+Bytes: 2 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: Set according to + result.
    • +
+

SRA + [HL]

+Shift right arithmetic value pointed by HL. +
+
[7] -> [7 -> 0] -> C
+
+Cycles: 4 +
+Bytes: 2 +
+Flags: See SRA r8 +

SRL + r8

+Shift right logic register r8. +
+
0 -> [7 -> 0] -> C
+
+Cycles: 2 +
+Bytes: 2 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: Set according to + result.
    • +
+

SRL + [HL]

+Shift right logic value pointed by HL. +
+
0 -> [7 -> 0] -> C
+
+Cycles: 4 +
+Bytes: 2 +
+Flags: See SRA r8 +

STOP

+Enter CPU very low power mode. Also used to switch between doube speed and + normal CPU modes in GBC. +
+Cycles: - +
+Bytes: 2 +
+Flags: None affected. +

SUB + A,r8

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

SUB + A,[HL]

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

SUB + A,n8

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

SWAP + r8

+Swap upper 4 bits in register r8 and the lower + ones. +
+Cycles: 2 +
+Bytes: 2 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: 0
    • +
+

SWAP + [HL]

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

XOR + A,r8

+Bitwise XOR between the value in r8 and + A. +
+Cycles: 1 +
+Bytes: 1 +
+Flags: +
    +
  • Z: Set if result is 0.
    • +
  • N: 0
    • +
  • H: 0
    • +
  • C: 0
    • +
+

XOR + A,[HL]

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

XOR + A,n8

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

SEE + ALSO

+rgbasm(1), rgbds(7) +

HISTORY

+rgbds was originally written by Carsten + Sørensen as part of the ASMotor package, and was later packaged in + RGBDS by Justin Lloyd. It is now maintained by a number of contributors at + https://github.com/rednex/rgbds.
+ + + + + +
April 17, 2017RGBDS Manual
+ + diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000..2cbabd35 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,32 @@ + + + + + General Information + + + +

RGBDS — Rednex Game Boy Development System

+

Table of Contents

+ + + + +

GitHub Repository:

+ + diff --git a/docs/rgbasm.1.html b/docs/rgbasm.1.html new file mode 100644 index 00000000..f3345f56 --- /dev/null +++ b/docs/rgbasm.1.html @@ -0,0 +1,146 @@ + + + + + + + RGBASM(1) + + + + + + + + +
RGBASM(1)General Commands ManualRGBASM(1)
+
+

NAME

+rgbasm — Game + Boy assembler +

SYNOPSIS

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

DESCRIPTION

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

EXAMPLES

+Assembling a basic source file is simple: +
+
$ rgbasm -o bar.o foo.asm
+
+The resulting object file is not yet a usable ROM image — it must first + be run through rgblink(1) and + rgbfix(1). +

SEE + ALSO

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

HISTORY

+rgbasm was originally written by Carsten + Sørensen as part of the ASMotor package, and was later packaged in + RGBDS by Justin Lloyd. It is now maintained by a number of contributors at + https://github.com/rednex/rgbds.
+ + + + + +
April 17, 2017RGBDS Manual
+ + diff --git a/docs/rgbasm.5.html b/docs/rgbasm.5.html new file mode 100644 index 00000000..019294bd --- /dev/null +++ b/docs/rgbasm.5.html @@ -0,0 +1,1459 @@ + + + + + + + RGBASM(5) + + + + + + + + +
RGBASM(5)File Formats ManualRGBASM(5)
+
+

NAME

+rgbasm — + language documentation +

DESCRIPTION

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

GENERAL

+

Syntax

+The syntax is line‐based, just as in any other assembler, meaning that + you do one instruction or pseudo‐op per line: +
+
[label] + [instruction] + [;comment]
+
+Example: +
+
John: ld a,87 ;Weee
+
+All pseudo‐ops, mnemonics and registers (reserved keywords) are + case‐insensitive and all labels are case‐sensitive. +

Sections

+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 "CoolStuff",ROMX
+
+This switches to the section called "CoolStuff" (or creates it if it + doesn't already exist) and it defines it as a code section. All sections + assembled at the same time that have the same name, type, etc, are considered + to be the same one, and their code is put together in the object file + generated by the assembler. All other sections must have a unique name, even + in different source files, or the linker will treat it as an error. +
+Possible section types are as follows: +
+
 
+
 
+
ROM0
+
A ROM section. Mapped to memory at $0000–$3FFF (or + $0000-$7FFF if tiny ROM mode is enabled in + rgblink(1)).
+
 
+
 
+
ROMX
+
A banked ROM section. Mapped to memory at + $4000–$7FFF. Valid banks range from 1 to 511. Not available if tiny + ROM mode is enabled in rgblink(1).
+
 
+
 
+
VRAM
+
A banked video RAM section. Mapped to memory at + $8000–$9FFF. Can only allocate memory, not fill it. Valid banks are + 0 and 1 but bank 1 isn't available if DMG mode is enabled in + rgblink(1).
+
 
+
 
+
SRAM
+
A banked external (save) RAM section. Mapped to memory at + $A000–$BFFF. Can only allocate memory, not fill it. Valid banks + range from 0 to 15.
+
 
+
 
+
WRAM0
+
A general-purpose RAM section. Mapped to memory at + $C000–$CFFF, or $C000-$DFFF if DMG mode is enabled in + rgblink(1). Can only allocate memory, not + fill it.
+
 
+
 
+
WRAMX
+
A banked general-purpose RAM section. Mapped to memory at + $D000–$DFFF. Can only allocate memory, not fill it. Valid banks + range from 1 to 7. Not available if DMG mode is enabled in + rgblink(1).
+
 
+
 
+
OAM
+
An object attributes RAM section. Mapped to memory at + $FE00-$FE9F. Can only allocate memory, not fill it.
+
 
+
 
+
HRAM
+
A high RAM section. Mapped to memory at $FF80–$FFFE. + Can only allocate memory, not fill it. +
+ 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 / + 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.
+
+
+A section is usually defined as a floating one, but the code can restrict where + the linker can place it. +
+If a section is defined with no indications, it is a floating section. The + linker will decide where to place it in the final binary and it has no + obligation to follow any specific rules. The following example defines a + section that can be placed anywhere in any ROMX bank: +
+
SECTION "CoolStuff",ROMX
+
+If it is needed, the following syntax can be used to fix the base address of the + section: +
+
SECTION + "CoolStuff",ROMX[$4567]
+
+It won't, however, fix the bank number, which is left to the linker. If you also + want to specify the bank you can do: +
+
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]
+
+In addition, you can specify byte alignment for a section. This ensures that the + section starts at a memory address where the given number of least-significant + bits are 0. This can be used along with BANK, if + desired. However, if an alignment is specified, the base address must be left + unassigned. This can be useful 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. +
+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. +

SYMBOLS

+

Symbols

+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
RSRESETResets the _RS counter to zero.
RSSET + constexprSets the _RS + counter to + constexpr.
RB + constexprSets the preceding symbol to + _RS and adds + constexpr to + _RS.
RW + constexprSets the preceding symbol to + _RS and adds + constexpr * 2 + to _RS.
RL + constexprSets the preceding symbol to + _RS and adds + constexpr * 4 + to _RS.
+
+ 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. This + means that, if you aren't careful, you may trap the assembler into an + infinite loop if there's a circular dependency in the expansions. Also, a + MACRO can have inside an EQUS which references the same MACRO, which has + the same problem.
+
MACRO
+
+
+ One of the best features of an assembler is the ability to write macros for + it. Macros also provide a method of passing arguments to them and they can + then react to the input using IF-constructs. +
+
+ 
+MyMacro: MACRO 
+         ld   a,80 
+         call MyFunc 
+         ENDM
+
+
+
+ Note that a colon (:) following the macro-name is required. Macros can't be + exported or imported. It's valid to call a macro from a macro (yes, even + the same one). +
+ The above example is a very simple macro. You execute the macro by typing + its name. +
+
+ 
+         add  a,b 
+         ld   sp,hl 
+         MyMacro ;This will be expanded 
+         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. +
+ SHIFT is a special command only available in + macros. Very useful in REPT-blocks. It will "shift" the + arguments by one "to the left". \1 + will get the value of \2, + \2 will get the value in + \3 and so forth. +
+ This is the only way of accessing the value of arguments from 10 to + 256.
+
+

Exporting + and importing symbols

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

Purging + symbols

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

Predeclared + Symbols

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

DEFINING + DATA

+

Defining + constant data

+DB defines a list of bytes that will be stored in + the final image. Ideal for tables and text (which is not zero-terminated). +
+
DB 1,2,3,4,"This is a + string"
+
+Alternatively, you can use DW to store a list of + words (16-bits) or DL to store a list of + doublewords/longs (32-bits). Strings are not allowed as arguments to + DW and DL. +
+You can also use DB, + DW and DL without + arguments, or leaving empty elements at any point in the list. This works + exactly like DS 1, DS + 2 and DS 4 respectively. Consequently, + DB, DW and + DL can be used in a + WRAM0 / + WRAMX / + HRAM / + VRAM / + SRAM section. +

Declaring + variables in a RAM 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
+

Including + binary files

+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

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

THE + MACRO LANGUAGE

+

Printing + things during assembly

+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" 
+PRINTV (2+3)/5 
+PRINTF MUL(3.14,3987.0)
+
+
+
+
PRINTT
+
prints out a string.
+
PRINTV
+
prints out an integer value or, as in the example, the + result of a calculation. Unsurprisingly, you can also print out a constant + symbols value.
+
PRINTF
+
prints out a fixed point value.
+
+

Automatically + repeating blocks of code

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

Aborting + the assembly process

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

Including + other source files

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

Conditional + assembling

+The four commands IF, + ELIF, ELSE, and + ENDC are used to conditionally assemble parts of + your file. This is a powerful feature commonly used in macros. +
+
+
+IF NUM < 0 
+  PRINTT "NUM < 0\n" 
+ELIF NUM == 0 
+  PRINTT "NUM == 0\n" 
+ELSE 
+  PRINTT "NUM > 0\n" 
+ENDC
+
+
+
+The ELIF and ELSE + blocks are optional. IF / + ELIF / + ELSE / + ENDC blocks can be nested. +
+Note that if an ELSE block is found before an + ELIF block, the ELIF + block will be ignored. All ELIF blocks must go + before the ELSE block. Also, if there is more + than one ELSE block, all of them but the first + one are ignored. +

Integer + and Boolean expressions

+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 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): + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperatorMeaning
()Precedence override
FUNC()Function call
~ + + -Unary not/plus/minus
* + / %Multiply/divide/modulo
<< + >>Shift left/right
& + | ^Binary and/or/xor
+ + -Add/subtract
!= + == <=Boolean comparison
>= + < >Boolean comparison (Same precedence as the + others)
&& + ||Boolean and/or
!Unary Boolean not
+
+The result of the boolean operators is zero if when FALSE and non-zero when + TRUE. It is legal to use an integer as the condition for IF blocks. You can + use symbols instead of numbers in your expression if you wish. +
+An expression is said to be constant when it doesn't change its value during + linking. This basically means that you can't use labels in those expressions. + The instructions in the macro-language all require expressions that are + constant. The only exception is the subtraction of labels in the same section + or labels that belong to sections with a fixed base addresses, all of which + must be defined in the same source file (the calculation cannot be passed to + the object file generated by the assembler). In this case, the result is a + constant that can be calculated at assembly time. +

Fixed‐point + Expressions

+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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameOperation
DIV(x,y)x/y
MUL(x,y)x*y
SIN(x)sin(x)
COS(x)cos(x)
TAN(x)tan(x)
ASIN(x)arcsin(x)
ACOS(x)arccos(x)
ATAN(x)arctan(x)
ATAN2(x,y)Angle between (x,y) and (1,0)
+
+These functions are extremely useful for automatic generation of various tables. + A circle has 65536.0 degrees. Sine values are between [-1.0; 1.0]. +
+
+
+; -- 
+; -- Generate a 256 byte sine table with values between 0 and 128 
+; -- 
+ANGLE SET   0.0 
+      REPT  256 
+      DB    (MUL(64.0,SIN(ANGLE))+64.0)>>16 
+ANGLE SET ANGLE+256.0 
+      ENDR
+
+
+

String + Expressions

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

Other + functions

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

MISCELLANEOUS

+

Changing + options while assembling

+OPT can be used to change some of the options + during assembling the source instead of defining them on the commandline. +
+OPT takes a comma-seperated list of options as its + argument: +
+
+
+PUSHO 
+OPT   g.oOX ;Set the GB graphics constants to use these characters 
+DW    `..ooOOXX 
+POPO 
+DW    `00112233
+
+
+
+The options that OPT can modify are currently: b, + e and g. +
+POPO and PUSHO provide + the interface to the option stack. PUSHO will + push the current set of options on the option stack. + POPO can then later be used to restore them. + Useful if you want to change some options in an include file and you don't + want to destroy the options set by the program that included your file. The + stacks number of entries is limited only by the amount of memory in your + machine. +

ALPHABETICAL + LIST OF KEYWORDS

+
+
@
+
+
__DATE__
+
+
__FILE__
+
+
__ISO_8601_LOCAL__
+
+
__ISO_8601_UTC__
+
+
__LINE__
+
+
__TIME__
+
+
__RGBDS_MAJOR__
+
+
__RGBDS_MINOR__
+
+
__RGBDS_PATCH__
+
+
__UTC_YEAR__
+
+
__UTC_MONTH__
+
+
__UTC_DAY__
+
+
__UTC_HOUR__
+
+
__UTC_MINUTE__
+
+
__UTC_SECOND__
+
+
_NARG
+
+
_PI
+
+
_RS
+
+
ACOS
+
+
ASIN
+
+
ATAN
+
+
ATAN2
+
+
BANK
+
+
COS
+
+
DB
+
+
DEF
+
+
DIV
+
+
DL
+
+
DS
+
+
DW
+
+
ELIF
+
+
ELSE
+
+
ENDC
+
+
ENDM
+
+
ENDR
+
+
EQU
+
+
EQUS
+
+
EXPORT
+
+
FAIL
+
+
GLOBAL
+
+
HIGH
+
+
HRAM
+
+
IF
+
+
INCBIN
+
+
INCLUDE
+
+
LOW
+
+
MACRO
+
+
MUL
+
+
OPT
+
+
POPO
+
+
POPS
+
+
PRINTF
+
+
PRINTT
+
+
PRINTV
+
+
PURGE
+
+
PUSHO
+
+
PUSHS
+
+
REPT
+
+
RB
+
+
RL
+
+
ROM0
+
+
ROMX
+
+
RSRESET
+
+
RSSET
+
+
RW
+
+
SECTION
+
+
SET
+
+
SHIFT
+
+
SIN
+
+
SRAM
+
+
STRCAT
+
+
STRCMP
+
+
STRIN
+
+
STRLEN
+
+
STRLWR
+
+
STRSUB
+
+
STRUPR
+
+
TAN
+
+
VRAM
+
+
WRAM0
+
+
WRAMX
+
+
WARN
+
+
+

SEE + ALSO

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

HISTORY

+rgbds was originally written by Carsten + Sørensen as part of the ASMotor package, and was later packaged in + RGBDS by Justin Lloyd. It is now maintained by a number of contributors at + https://github.com/rednex/rgbds.
+ + + + + +
January 7, 2018RGBDS Manual
+ + diff --git a/docs/rgbds.5.html b/docs/rgbds.5.html new file mode 100644 index 00000000..0d327629 --- /dev/null +++ b/docs/rgbds.5.html @@ -0,0 +1,306 @@ + + + + + + + RGBDS(5) + + + + + + + + +
RGBDS(5)File Formats ManualRGBDS(5)
+
+

NAME

+rgbds — object + file format documentation +

DESCRIPTION

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

FILE + STRUCTURE

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

RPN + 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 + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueMeaning
$00+ + operator
$01- + operator
$02* + operator
$03/ + operator
$04% + operator
$05unary + -
$10| + operator
$11& + operator
$12^ + operator
$13unary + ~
$21&& + comparison
$22|| + comparison
$23unary!
$30== + comparison
$31!= + comparison
$32> + comparison
$33< + comparison
$34>= + comparison
$35<= + comparison
$40<< + comparison
$41>> + comparison
$50BANK(symbol), + a LONG Symbol ID follows.
$51BANK(section_name), + a null-terminated string follows.
$52Current + BANK().
$60HRAMCheck. + Check if the value is in HRAM, AND it with 0xFF.
$80LONG integer + follows.
$81LONG Symbol ID + follows.
+

SEE + ALSO

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

HISTORY

+rgbds was originally written by Carsten + Sørensen as part of the ASMotor package, and was later packaged in + RGBDS by Justin Lloyd. It is now maintained by a number of contributors at + https://github.com/rednex/rgbds.
+ + + + + +
January 7, 2018RGBDS Manual
+ + diff --git a/docs/rgbfix.1.html b/docs/rgbfix.1.html new file mode 100644 index 00000000..159d3e7a --- /dev/null +++ b/docs/rgbfix.1.html @@ -0,0 +1,187 @@ + + + + + + + RGBFIX(1) + + + + + + + + +
RGBFIX(1)General Commands ManualRGBFIX(1)
+
+

NAME

+rgbfix — Game + Boy checksum fixer +

SYNOPSIS

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

DESCRIPTION

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

EXAMPLES

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

SEE + ALSO

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

HISTORY

+rgbfix was originally released by Carsten + Sørensen as a standalone program called gbfix, and was later packaged + in RGBDS by Justin Lloyd. It is now maintained by a number of contributors at + https://github.com/rednex/rgbds.
+ + + + + +
April 17, 2017RGBDS Manual
+ + diff --git a/docs/rgbgfx.1.html b/docs/rgbgfx.1.html new file mode 100644 index 00000000..6f435466 --- /dev/null +++ b/docs/rgbgfx.1.html @@ -0,0 +1,153 @@ + + + + + + + RGBGFX(1) + + + + + + + + +
RGBGFX(1)General Commands ManualRGBGFX(1)
+
+

NAME

+rgbgfx — Game + Boy graphics converter +

SYNOPSIS

+ + + + + +
rgbgfx[-DfFhPTVv] + [-o + outfile] + [-d + depth] + [-p + palfile] + [-t + mapfile] + [-x + tiles] + file
+

DESCRIPTION

+The rgbgfx program converts PNG images into the + Nintendo Game Boy's planar tile format. The arguments are as follows: +
+
 
+
 
+
-D
+
Debug features are enabled.
+
 
+
 
+
-f
+
Fix the input PNG file to be a correctly indexed + image.
+
 
+
 
+
-F
+
Same as -f, but additionally, + the input PNG file is fixed to have its parameters match the command + line's parameters.
+
 
+
 
+
-d + depth
+
The bitdepth of the output image (either 1 or 2). By + default, the bitdepth is 2 (two bits per pixel).
+
 
+
 
+
-h
+
Lay out tiles horizontally rather than vertically.
+
 
+
 
+
-o + outfile
+
The name of the output file.
+
 
+
 
+
-p + palfile
+
Raw bytes (8 bytes for two bits per pixel, 4 bytes for one + bit per pixel) containing the RGB15 values in the little-endian byte order + and then ordered from lightest to darkest.
+
 
+
 
+
-P
+
Same as -p, but the pallete + file output name is made by taking the input filename, removing the file + extension, and appending .pal.
+
 
+
 
+
-t + mapfile
+
If any tiles are the same, don't place the repeat tiles in + the output file, and make a tilemap file.
+
 
+
 
+
-T
+
Same as -t, but the tilemap + file output name is made by taking the input filename, removing the file + extension, and appending .tilemap.
+
 
+
 
+
-u
+
Truncate repeated tiles. Useful with tilemaps.
+
 
+
 
+
-V
+
Print the version of the program and exit.
+
 
+
 
+
-v
+
Verbose. Print errors when the command line parameters and + the parameters in the PNG file don't match.
+
 
+
 
+
-x + tiles
+
Trim the end of the output file by this many tiles.
+
+

EXAMPLES

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

SEE + ALSO

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

HISTORY

+rgbgfx was created by + stag019 to be included in RGBDS. It is now + maintained by a number of contributors at + https://github.com/rednex/rgbds.
+ + + + + +
April 17, 2017RGBDS Manual
+ + diff --git a/docs/rgblink.1.html b/docs/rgblink.1.html new file mode 100644 index 00000000..99d63dd1 --- /dev/null +++ b/docs/rgblink.1.html @@ -0,0 +1,161 @@ + + + + + + + RGBLINK(1) + + + + + + + + +
RGBLINK(1)General Commands ManualRGBLINK(1)
+
+

NAME

+rgblink — Game + Boy linker +

SYNOPSIS

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

DESCRIPTION

+The rgblink program links objects created by + rgbasm(1) into a single Game Boy ROM file. +
+By default, ROM0 sections created by the assembler are placed in the 16KiB bank + 0, and ROMX sections are placed in any bank except bank 0. If your ROM will + only be 32KiB, you can use the -t option to + override this. +
+Similarly, WRAM0 sections are placed in the first 4KiB of WRAM bank 0 and WRAMX + sections are placed in any bank except bank 0. If your ROM doesn't use banked + WRAM you can use option -w option to override + this. +
+Also, if your ROM is designed for DMG, you can make sure that you don't use any + prohibited section by using the option -d, which + implies -w but also prohibits the use of VRAM + bank 1. +
+The arguments are as follows: +
+
 
+
 
+
-m + mapfile
+
Write a mapfile to the given filename.
+
 
+
 
+
-n + symfile
+
Write a symbol file to the given filename.
+
 
+
 
+
-O + overlayfile
+
The ROM image to overlay sections over. When an overlay ROM + is provided, all sections must be fixed. This may be used to patch an + existing binray.
+
 
+
 
+
-o + outfile
+
Write ROM image to the given filename.
+
 
+
 
+
-p + pad_value
+
When padding an image, pad with this value. The default is + 0x00.
+
 
+
 
+
-s + symbol
+
???
+
 
+
 
+
-w
+
Expand the WRAM0 section size from 4KiB to the full 8KiB + assigned to WRAM and prohibit the use of WRAMX sections.
+
 
+
 
+
-d
+
Enable DMG mode. Prohibit the use of sections that doesn't + exist on a DMG, such as WRAMX and VRAM bank 1. This option automatically + enables -w.
+
 
+
 
+
-t
+
Expand the ROM0 section size from 16KiB to the full 32KiB + assigned to ROM and prohibit the use of ROMX sections. Useful for ROMs + that fit in 32 KiB.
+
 
+
 
+
-l + linkerscript
+
Specify a linkerscript file that tells the linker how + sections must be placed in the ROM. This file has priority over the + attributes assigned in the source code, but they have to be consistent. + See rgblink(5) for more information about its + format.
+
 
+
 
+
-V
+
Print the version of the program and exit.
+
+

EXAMPLES

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

SEE + ALSO

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

HISTORY

+rgblink was originally written by Carsten + Sørensen as part of the ASMotor package, and was later packaged in + RGBDS by Justin Lloyd. It is now maintained by a number of contributors at + https://github.com/rednex/rgbds.
+ + + + + +
April 17, 2017RGBDS Manual
+ + diff --git a/docs/rgblink.5.html b/docs/rgblink.5.html new file mode 100644 index 00000000..c719cbf9 --- /dev/null +++ b/docs/rgblink.5.html @@ -0,0 +1,105 @@ + + + + + + + RGBLINK(5) + + + + + + + + +
RGBLINK(5)File Formats ManualRGBLINK(5)
+
+

NAME

+rgblink — + linkerscript file format +

DESCRIPTION

+The linkerscript is an external file that allows the user to specify the order + of sections without the need for doing so before assembling each object file. +
+The placement of sections specified in the linkerscript is done before the + sections whose placement is defined in the source code. +
+A linkerscript consists on a series of banks followed by a list of sections and, + optionally, commands. They can be lowercase or uppercase, it is ignored. Any + line can contain a comment starting with + ‘;’ that ends at the end of the line: +
+
+
+ROMX $F ; This is a comment 
+  "Functions to read array" 
+  ALIGN 8 
+  "Array aligned to 256 bytes" 
+ 
+WRAMX 2 
+  "Some variables"
+
+
+
+Numbers can be in decimal or hexadecimal format (the prefix is + ‘$’). It is an error if any bank 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. +
+When a new bank statement is found, sections found after it will be placed right + from the beginning of that bank. If the linkerscript switches to a different + bank and then it comes back to the previous one it will continue from the last + address that was used. +
+The only two commands are ORG and + ALIGN: +
    +
  • ORG sets the address in + which new sections will be placed. It can not be lower than the current + address.
    • +
  • ALIGN will increase the + address until it is aligned to the specified boundary (it tries to set to + 0 the number of bits specified after the command: + ALIGN 8 will align to $100).
    • +
+
+Note: The bank, alignment, address and type of sections can be specified both in + the source code and in the linkerscript. For a section to be able to be placed + with the linkerscript the bank must be left unassigned in the source code or + be the same as the one specified in the linkerscript. The address and + alignment musn't be set. +

SEE + ALSO

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

HISTORY

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