1RGBLINK(5)                  BSD File Formats Manual                 RGBLINK(5)
2

NAME

4     rgblink — linker script file format
5

DESCRIPTION

7     The linker script is an external file that allows the user to specify the
8     order of sections at link time and in a centralized manner.
9
10     A linker script consists of a series of bank declarations, each option‐
11     ally followed by a list of section names (in double quotes) or commands.
12     All reserved keywords (bank types and command names) are case-insensi‐
13     tive; all section names are case-sensitive.
14
15     Any line can contain a comment starting with ‘;’ that ends at the end of
16     the line.
17
18           ; This line is a comment
19           ROMX $F            ; start a bank
20             "Some functions" ; a section name
21             ALIGN 8          ; a command
22             "Some array"
23
24           WRAMX 2            ; start another bank
25             org $d123        ; another command
26             "Some variables"
27
28     Numbers can be in decimal or hexadecimal format (the prefix is ‘$’).  It
29     is an error if any section name or command is found before setting a
30     bank.
31
32     Files can be included by using the INCLUDE keyword, followed by a string
33     with the path of the file that has to be included.
34
35     The possible bank types are: ROM0, ROMX, VRAM, SRAM, WRAM0, WRAMX, OAM
36     and HRAM.  Unless there is a single bank, which can occur with types
37     ROMX, VRAM, SRAM and WRAMX, it is needed to specify a bank number after
38     the type.
39
40     Section names in double quotes support the same character escape se‐
41     quences as strings in rgbasm(5), specifically ‘\\’, ‘\"’, ‘\n’, ‘\r’, and
42     ‘\t’.  Other backslash escape sequences in rgbasm(5) are only relevant to
43     assembly code and do not apply in section names.
44
45     When a new bank statement is found, sections found after it will be
46     placed right from the beginning of that bank.  If the linker script
47     switches to a different bank and then comes back to a previous one, it
48     will continue from the last address that was used.
49
50     The only two commands are ORG and ALIGN:
51
52     •   ORG sets the address in which new sections will be placed.  It can
53         not be lower than the current address.
54
55     •   ALIGN will increase the address until it is aligned to the specified
56         boundary (it tries to set to 0 the number of bits specified after the
57         command: ‘ALIGN 8’ will align to $100).
58
59     Note: The bank, alignment, address and type of sections can be specified
60     both in the source code and in the linker script.  For a section to be
61     able to be placed with the linker script, the bank, address and alignment
62     must be left unassigned in the source code or be compatible with what is
63     specified in the linker script.  For example, ‘ALIGN[8]’ in the source
64     code is compatible with ‘ORG $F00’ in the linker script.
65

SEE ALSO

67     rgbasm(1), rgblink(1), rgbfix(1), rgbds(5), rgbds(7)
68

HISTORY

70     rgblink was originally written by Carsten Sørensen as part of the ASMotor
71     package, and was later packaged in RGBDS by Justin Lloyd.  It is now
72     maintained by a number of contributors at https://github.com/gbdev/rgbds
73
74BSD                             March 28, 2021                             BSD
Impressum