|
16 | 16 | .Op Fl o Ar out_file
|
17 | 17 | .Op Fl p Ar pad_value
|
18 | 18 | .Op Fl S Ar spec
|
| 19 | +.Op Fl s Ar symbol |
19 | 20 | .Ar
|
20 | 21 | .Sh DESCRIPTION
|
21 | 22 | The
|
|
104 | 105 | .Sx Scrambling algorithm
|
105 | 106 | below for an explanation and a description of
|
106 | 107 | .Ar spec .
|
| 108 | +.It Fl s Ar sect_name , Fl Fl smart Ar sect_name |
| 109 | +This option specifies the name of a section that will be used as a starting point for smart linking; it may appear several times per |
| 110 | +.Nm |
| 111 | +invocation. |
| 112 | +See |
| 113 | +.Sx SMART LINKING |
| 114 | +below. |
| 115 | +If no section with that name is found, |
| 116 | +.Nm |
| 117 | +will error out. |
107 | 118 | .It Fl t , Fl \-tiny
|
108 | 119 | Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to ROM.
|
109 | 120 | ROMX sections that are fixed to a bank other than 1 become errors, other ROMX sections are treated as ROM0.
|
@@ -191,6 +202,103 @@ to fix these so that the program will actually run in a Game Boy:
|
191 | 202 | Here is a more complete example:
|
192 | 203 | .Pp
|
193 | 204 | .Dl $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o obj/engine.o
|
| 205 | +.Sh SMART LINKING |
| 206 | +Smart linking is a feature of |
| 207 | +.Nm |
| 208 | +that allows "trimming the fat" off of a ROM. |
| 209 | +It is enabled only if at least one |
| 210 | +.Fl s |
| 211 | +option is given on the command line. |
| 212 | +.Pp |
| 213 | +The smart linking process begins by finding all the |
| 214 | +.Ql referenced |
| 215 | +sections. |
| 216 | +A section is referenced if its name is specified using a |
| 217 | +.Fl s |
| 218 | +option, or if it is referred to by a referenced section. |
| 219 | +This definition applies recursively, so if section |
| 220 | +.Ql A |
| 221 | +is specified using |
| 222 | +.Fl s Va A , |
| 223 | +section |
| 224 | +.Ql A |
| 225 | +references section |
| 226 | +.Ql B , |
| 227 | +and section |
| 228 | +.Ql B |
| 229 | +references section |
| 230 | +.Ql C , |
| 231 | +then all three sections |
| 232 | +.Ql A , |
| 233 | +.Ql B , |
| 234 | +and |
| 235 | +.Ql C |
| 236 | +are referenced. |
| 237 | +.Pp |
| 238 | +Sections refer to each other through expressions. For example: |
| 239 | +.Bd -literal -offset indent |
| 240 | +SECTION "A", ROM0 |
| 241 | + db Someplace |
| 242 | + db BANK("C") |
| 243 | +SECTION "B", ROM0 |
| 244 | +Someplace: |
| 245 | +SECTION "C", ROMX |
| 246 | + db 42 |
| 247 | +.Ed |
| 248 | +Here, section |
| 249 | +.Ql A |
| 250 | +references section |
| 251 | +.Ql B |
| 252 | +via the label |
| 253 | +.Ql Someplace , |
| 254 | +and references section |
| 255 | +.Ql C |
| 256 | +via its name in |
| 257 | +.Ql BANK("C") . |
| 258 | +.Pp |
| 259 | +After all the referenced sections are found, all sections that were not referenced are deleted, and the linking process continues as normal. |
| 260 | +.Sy This should not cause any symbols not to be found, please report a bug (see Sx BUGS Ns Sy ) if this occurs. |
| 261 | +.Pp |
| 262 | +This is useful to detect |
| 263 | +.Dq unused |
| 264 | +sections, i.e. sections that contain data not used by anything. |
| 265 | +Typically, the section containing the header, including the entry point at |
| 266 | +.Ad $00:0100 |
| 267 | +will be one of the starting sections; more exotic use cases may require more starting sections. |
| 268 | +It may be a good idea to start with the header as the only root, and if needed, add more root sections. |
| 269 | +.Pp |
| 270 | +Be careful, as numeric expressions do |
| 271 | +.Sy not |
| 272 | +cause references: |
| 273 | +.Bd -literal -offset indent |
| 274 | +DEF BASE_ADDR EQU $4000 |
| 275 | +SECTION "A", ROM0 |
| 276 | + dw BASE_ADDR |
| 277 | +SECTION "B", ROMX[BASE_ADDR] |
| 278 | + db 42 |
| 279 | +.Ed |
| 280 | +Section |
| 281 | +.Ql A |
| 282 | +does |
| 283 | +.Sy not |
| 284 | +reference section |
| 285 | +.Ql B , |
| 286 | +since |
| 287 | +.Va BASE_ADDR |
| 288 | +is a constant, and thus does not belong to section |
| 289 | +.Ql B . |
| 290 | +.Pp |
| 291 | +Finally, be careful that |
| 292 | +.Xr rgbasm 1 |
| 293 | +tries to fill in data by itself to speed up |
| 294 | +.Nm Ap s |
| 295 | +work, which may cause |
| 296 | +.Nm |
| 297 | +not to see references to sections whose bank and/or address are fixed. |
| 298 | +It may be advisable to avoid fixing those (notably, to enable |
| 299 | +.Nm |
| 300 | +to improve section placement), but they can still be manually referenced using |
| 301 | +.Fl s . |
194 | 302 | .Sh BUGS
|
195 | 303 | Please report bugs on
|
196 | 304 | .Lk https://github.com/gbdev/rgbds/issues GitHub .
|
|
0 commit comments