1RGBLINK(1) BSD General Commands Manual RGBLINK(1)
2
4 rgblink — Game Boy linker
5
7 rgblink [-dMtVvwx] [-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, --no-sym-in-map
45 If specified, the map file will not list symbols, only sections.
46 -m map_file, --map map_file
48 Write a map file to the given filename, listing how sections and
49 symbols were assigned.
50 -n sym_file, --sym sym_file
52 Write a symbol file to the given filename, listing the address of
53 all exported symbols. Several external programs can use this in‐
54 formation, for example to help debugging ROMs.
55 -O overlay_file, --overlay overlay_file
57 If specified, sections will be overlaid "on top" of the provided
58 ROM image. In that case, all sections must be fixed. This may
59 be used to patch an existing binary.
60 -o out_file, --output out_file
62 Write the ROM image to the given file.
63 -p pad_value, --pad pad_value
65 When inserting padding between sections, pad with this value.
66 Has no effect if -O is specified. The default is 0.
67 -S spec, --scramble spec
69 Enables a different “scrambling” algorithm for placing sections.
70 See Scrambling algorithm below for an explanation and a descrip‐
71 tion of spec.
72 -s symbol, --smart symbol
74 This option is ignored. It was supposed to perform smart linking
75 but fell into disrepair, and so has been removed. It will be re‐
76 implemented at some point.
77 -t, --tiny
79 Expand the ROM0 section size from 16 KiB to the full 32 KiB as‐
80 signed to ROM. ROMX sections that are fixed to a bank other than
81 1 become errors, other ROMX sections are treated as ROM0. Useful
82 for ROMs that fit in 32 KiB.
83 -V, --version
85 Print the version of the program and exit.
86 -v, --verbose
88 Verbose: enable printing more information to standard error.
89 -w, --wramx
91 Expand the WRAM0 section size from 4 KiB to the full 8 KiB as‐
92 signed to WRAM. WRAMX sections that are fixed to a bank other
93 than 1 become errors, other WRAMX sections are treated as WRAM0.
94 -x, --nopad
96 Disables padding the end of the final file. This option automat‐
97 ically enables -t. You can use this when not not making a ROM.
98 When making a ROM, be careful that not using this is not a re‐
99 placement for rgbfix(1)'s -p option!
100 Scrambling algorithm
102 The default section placement algorithm tries to minimize the number of
103 banks used; “scrambling” instead places sections into a given pool of
104 banks, trying to minimize the number of sections sharing a given bank.
105 This is useful to catch broken bank assumptions, such as expecting two
106 different sections to land in the same bank (that is not guaranteed un‐
107 less both are manually assigned the same bank number).
108 A scrambling spec is a comma-separated list of region specs. A trailing
110 comma is allowed, as well as whitespace between all specs and their com‐
111 ponents. Each region spec has the following form:
112 region[=size]
113 region must be one of the following (case-insensitive), while size must
114 be a positive decimal integer between 1 and the corresponding maximum.
115 Certain regions allow omitting the size, in which case it defaults to its
116 max value.
117 Region name Ta Max size Ta Size optional
119 romx 65535 No
120 sram 255 No
121 wramx 7 Yes
122 A size of 0 disables scrambling for that region.
124 For example, ‘romx=64,wramx=4’ will scramble ROMX sections among ROM
126 banks 1 to 64, WRAMX sections among RAM banks 1 to 4, and will not scram‐
127 ble SRAM sections.
128 Later region specs override earlier ones; for example, ‘romx=42, Romx=0’
130 disables scrambling for romx.
131 wramx scrambling is silently ignored if -w is passed (including if im‐
133 plied by -d), as WRAMX sections will be treated as WRAM0.
134
136 All you need for a basic ROM is an object file, which can be made into a
137 ROM image like so:
138 $ rgblink -o bar.gb foo.o
140 The resulting bar.gb will not have correct checksums (unless you put them
142 in the assembly source). You should use rgbfix(1) to fix these so that
143 the program will actually run in a Game Boy:
144 $ rgbfix -v bar.gb
146 Here is a more complete example:
148 $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o
150 obj/engine.o
151
153 Please report bugs on GitHub: https://github.com/gbdev/rgbds/issues
154
156 rgbasm(1), rgblink(5), rgbfix(1), rgbds(5), rgbds(7)
157
159 rgblink was originally written by Carsten Sørensen as part of the ASMotor
160 package, and was later packaged in RGBDS by Justin Lloyd. It is now
161 maintained by a number of contributors at https://github.com/gbdev/rgbds
162BSD March 28, 2021 BSD