1RGBLINK(1) BSD General Commands Manual RGBLINK(1)
2
4 rgblink — Game Boy linker
5
7 rgblink [-dtVvwx] [-l linker_script] [-m map_file] [-n sym_file]
8 [-O overlay_file] [-o out_file] [-p pad_value] [-S spec]
9 [-s symbol] file ...
10
12 The rgblink program links RGB object files, typically created by
13 rgbasm(1), into a single Game Boy ROM file. The format is documented in
14 rgbds(5).
15 ROM0 sections are placed in the first 16 KiB of the output ROM, and ROMX
17 sections are placed in any 16 KiB “bank” except the first. If your ROM
18 will only be 32 KiB, you can use the -t option to change this.
19 Similarly, WRAM0 sections are placed in the first 4 KiB of WRAM (“bank
21 0”), and WRAMX sections are placed in any bank of the last 4 KiB. If
22 your ROM doesn't use banked WRAM, you can use the -w option to change
23 this.
24 Also, if your ROM is designed for a monochrome Game Boy, you can make
26 sure that you don't use any incompatible section by using the -d option,
27 which implies -w but also prohibits the use of banked VRAM.
28 Note that options can be abbreviated as long as the abbreviation is unam‐
30 biguous: --verb is --verbose, but --ver is invalid because it could also
31 be --version. The arguments are as follows:
32 -d, --dmg
34 Enable DMG mode. Prohibit the use of sections that doesn't exist
35 on a DMG, such as VRAM bank 1. This option automatically enables
36 -w.
37 -l linker_script, --linkerscript linker_script
39 Specify a linker script file that tells the linker how sections
40 must be placed in the ROM. The attributes assigned in the linker
41 script must be consistent with any assigned in the code. See
42 rgblink(5) for more information about the linker script format.
43 -m map_file, --map map_file
45 Write a map file to the given filename, listing how sections and
46 symbols were assigned.
47 -n sym_file, --sym sym_file
49 Write a symbol file to the given filename, listing the address of
50 all exported symbols. Several external programs can use this in‐
51 formation, for example to help debugging ROMs.
52 -O overlay_file, --overlay overlay_file
54 If specified, sections will be overlaid "on top" of the provided
55 ROM image. In that case, all sections must be fixed. This may
56 be used to patch an existing binary.
57 -o out_file, --output out_file
59 Write the ROM image to the given file.
60 -p pad_value, --pad pad_value
62 When inserting padding between sections, pad with this value.
63 Has no effect if -O is specified. The default is 0.
64 -S spec, --scramble spec
66 Enables a different “scrambling” algorithm for placing sections.
67 See Scrambling algorithm below for an explanation and a descrip‐
68 tion of spec.
69 -s symbol, --smart symbol
71 This option is ignored. It was supposed to perform smart linking
72 but fell into disrepair, and so has been removed. It will be re‐
73 implemented at some point.
74 -t, --tiny
76 Expand the ROM0 section size from 16 KiB to the full 32 KiB as‐
77 signed to ROM. ROMX sections that are fixed to a bank other than
78 1 become errors, other ROMX sections are treated as ROM0. Useful
79 for ROMs that fit in 32 KiB.
80 -V, --version
82 Print the version of the program and exit.
83 -v, --verbose
85 Verbose: enable printing more information to standard error.
86 -w, --wramx
88 Expand the WRAM0 section size from 4 KiB to the full 8 KiB as‐
89 signed to WRAM. WRAMX sections that are fixed to a bank other
90 than 1 become errors, other WRAMX sections are treated as WRAM0.
91 -x, --nopad
93 Disables padding the end of the final file. This option automat‐
94 ically enables -t. You can use this when not not making a ROM.
95 When making a ROM, be careful that not using this is not a re‐
96 placement for rgbfix(1)'s -p option!
97 Scrambling algorithm
99 The default section placement algorithm tries to minimize the number of
100 banks used; “scrambling” instead places sections into a given pool of
101 banks, trying to minimize the number of sections sharing a given bank.
102 This is useful to catch broken bank assumptions, such as expecting two
103 different sections to land in the same bank (that is not guaranteed un‐
104 less both are manually assigned the same bank number).
105 A scrambling spec is a comma-separated list of region specs. A trailing
107 comma is allowed, as well as whitespace between all specs and their com‐
108 ponents. Each region spec has the following form:
109 region[=size]
110 region must be one of the following (case-insensitive), while size must
111 be a positive decimal integer between 1 and the corresponding maximum.
112 Certain regions allow omitting the size, in which case it defaults to its
113 max value.
114 Region name Ta Max size Ta Size optional
116 romx 65535 No
117 sram 255 No
118 wramx 7 Yes
119 A size of 0 disables scrambling for that region.
121 For example, ‘romx=64,wramx=4’ will scramble ROMX sections among ROM
123 banks 1 to 64, WRAMX sections among RAM banks 1 to 4, and will not scram‐
124 ble SRAM sections.
125 Later region specs override earlier ones; for example, ‘romx=42, Romx=0’
127 disables scrambling for romx.
128 wramx scrambling is silently ignored if -w is passed (including if im‐
130 plied by -d), as WRAMX sections will be treated as WRAM0.
131
133 All you need for a basic ROM is an object file, which can be made into a
134 ROM image like so:
135 $ rgblink -o bar.gb foo.o
137 The resulting bar.gb will not have correct checksums (unless you put them
139 in the assembly source). You should use rgbfix(1) to fix these so that
140 the program will actually run in a Game Boy:
141 $ rgbfix -v bar.gb
143 Here is a more complete example:
145 $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o
147 obj/engine.o
148
150 Please report bugs on GitHub: https://github.com/gbdev/rgbds/issues
151
153 rgbasm(1), rgblink(5), rgbfix(1), rgbds(5), rgbds(7)
154
156 rgblink was originally written by Carsten Sørensen as part of the ASMotor
157 package, and was later packaged in RGBDS by Justin Lloyd. It is now
158 maintained by a number of contributors at https://github.com/gbdev/rgbds
159BSD March 28, 2021 BSD