Skip to content

Commit ccf9dcb

Browse files
ISSOtmISSOtm
authored
Improve linker scripts a little (#1275)
* Allow for optional sections in linker scripts These are more useful for frameworks/toolchains. * Check for an active mem region everywhere Do you like segfaults? Too bad! * Allow the address to be floating in linker scripts Try and make the life of SDCC interop easier. * Also validate alignment when floating * Overhaul the linker script manual page Documenting the new features, but also restructuring the existing documentation to make the manual page (hopefully) easier to understand.
1 parent 7b199d7 commit ccf9dcb

File tree

2 files changed

+244
-111
lines changed

2 files changed

+244
-111
lines changed

‎man/rgblink.5

+129-73
Original file line numberDiff line numberDiff line change
@@ -7,47 +7,41 @@
77
.Nm rgblink
88
.Nd linker script file format
99
.Sh DESCRIPTION
10-
The linker script is an external file that allows the user to specify the order of sections at link time and in a centralized manner.
10+
The linker script is a file that allows specifying attributes for sections at link time, and in a centralized manner.
11+
There can only be one linker script per invocation of
12+
.Nm ,
13+
but it can be split into several files
14+
.Pq using the Ic INCLUDE No directive .
15+
.Ss Basic syntax
16+
The linker script syntax is line-based.
17+
Each line may have a directive or section name, a comment, both, or neither.
18+
Whitespace (space and tab characters) is used to separate syntax elements, but is otherwise ignored.
1119
.Pp
12-
A linker script consists of a series of bank declarations, each optionally followed by a list of section names (in double quotes) or directives.
13-
All reserved keywords (bank types and directive names) are case-insensitive; all section names are case-sensitive.
14-
.Pp
15-
Any line can contain a comment starting with
20+
Comments begin with a semicolon
1621
.Ql \&;
17-
that ends at the end of the line.
18-
.Bd -literal -offset indent
19-
; This line is a comment
20-
ROMX $F ; start a bank
21-
"Some functions" ; a section name
22-
ALIGN 8 ; a directive
23-
"Some array"
24-
25-
WRAMX 2 ; start another bank
26-
org $d123 ; another directive
27-
"Some variables"
28-
.Ed
29-
.Pp
30-
Numbers can be in decimal or hexadecimal format
31-
.Pq the prefix is Ql $ .
32-
It is an error if any section name or directive is found before setting a bank.
22+
character, until the end of the line.
23+
They are simply ignored.
3324
.Pp
34-
Files can be included by using the
35-
.Ic INCLUDE
36-
keyword, followed by a string with the path of the file that has to be included.
25+
Keywords are composed of letters and digits (but they can't start with a digit); they are all case-insensitive.
3726
.Pp
38-
The possible bank types are:
39-
.Cm ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM
40-
and
41-
.Cm HRAM .
42-
Unless there is a single bank, which can occur with types
43-
.Cm ROMX , VRAM , SRAM
44-
and
45-
.Cm WRAMX ,
46-
it is mandatory to specify a bank number after the type.
47-
.Pp
48-
Section names in double quotes support the same character escape sequences as strings in
27+
Numbers can be written in decimal format, or in binary using the
28+
.Ql %
29+
prefix, or in hexadecimal using the
30+
.Ql $
31+
prefix (hexadecimal digits are case-insensitive).
32+
Note that unlike
4933
.Xr rgbasm 5 ,
50-
specifically
34+
an octal
35+
.Ql &
36+
prefix is not supported, nor are
37+
.Ql _
38+
digit separators.
39+
.Pp
40+
Strings begin with a double quote, and end at the next (non-escaped) double quote.
41+
Strings must not contain literal newline characters.
42+
Most of the same character escapes as
43+
.Xr rgbasm 5
44+
are supported, specifically
5145
.Ql \e\e ,
5246
.Ql \e" ,
5347
.Ql \en ,
@@ -56,51 +50,113 @@ and
5650
.Ql \et .
5751
Other backslash escape sequences in
5852
.Xr rgbasm 5
59-
are only relevant to assembly code and do not apply in section names.
53+
are only relevant to assembly code and do not apply in linker scripts.
54+
.Ss Directives
55+
.Bl -tag -width Ds
56+
.It Including other files
57+
.Ql Ic INCLUDE Ar path
58+
acts as if the contents of the file at
59+
.Ar path
60+
were copy-pasted in place of the
61+
.Ic INCLUDE
62+
directive.
63+
.Ar path
64+
must be a string.
65+
.It Specifying the active bank
66+
.Tg region
67+
The active bank can be set by specifying its type (memory region) and number.
68+
The possible types are:
69+
.Ic ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM ,
70+
and
71+
.Ic HRAM .
72+
The bank number can be omitted from the types that only contain a single bank, which are:
73+
.Ic ROM0 ,
74+
.Ic ROMX No if Fl t No is passed to Xr rgblink 1 ,
75+
.Ic VRAM No if Fl d No is passed to Xr rgblink 1 ,
76+
.Ic WRAM0 ,
77+
.Ic WRAMX No if Fl w No is passed to Xr rgblink 1 ,
78+
.Ic OAM ,
79+
and
80+
.Ic HRAM .
81+
.Pq Ic SRAM No is the only type that can never have its bank number omitted.
6082
.Pp
61-
When a new bank statement is found, sections found after it will be placed right from the beginning of that bank.
62-
If the linker script switches to a different bank and then comes back to a previous one, it will continue from the last address that was used.
83+
After a bank specification, the
84+
.Dq current address
85+
is set to the last value it had for that bank.
86+
If the bank has never been active thus far, the
87+
.Dq current address
88+
defaults to the beginning of the bank
89+
.Pq e.g. Ad $4000 No for Ic ROMX No sections .
90+
.It Changing the current address
91+
A bank must be active for any of these directives to be used.
6392
.Pp
64-
The only three directives are
65-
.Ic ORG ,
66-
.Ic ALIGN ,
67-
and
68-
.Ic DS :
69-
.Bl -bullet
70-
.It
71-
.Ic ORG Ar addr
72-
sets the address in which new sections will be placed to
93+
.Ql Ic ORG Ar addr
94+
sets the
95+
.Dq current address
96+
to
7397
.Ar addr .
74-
It can not be lower than the current address.
75-
.It
76-
.Ic ALIGN Ar addr
77-
or
78-
.Ic ALIGN Ar addr , Ar offset
79-
will increase the address until it is aligned to the specified boundary
80-
.Po it tries to set to
98+
This directive cannot be used to move the address backwards:
99+
.Ar addr
100+
must be greater than or equal to the
101+
.Dq current address .
102+
.Pp
103+
.Ql Ic FLOATING
104+
causes all sections between it and the next
105+
.Ic ORG
106+
or bank specification to be placed at addresses automatically determined by
107+
.Nm .
108+
.Pp
109+
.Ql Ic ALIGN Ar addr , Ar offset
110+
increases the
111+
.Dq current address
112+
until it is aligned to the specified boundary (i.e. the
113+
.Ar align
114+
lowest bits of the address are equal to
115+
.Ar offset ) .
116+
If
81117
.Ar offset
82-
the number of bits specified by
83-
.Ar align :
84-
for example,
118+
is omitted, it is implied to be 0.
119+
For example, if the
120+
.Dq current address
121+
is $0007,
85122
.Ql ALIGN 8
86-
will align to $100 ,
87-
and
123+
would set it to $0100, and
88124
.Ql ALIGN 8 , 10
89-
will align to $10A
90-
.Pc .
91-
.It
92-
.Ic DS
93-
will increase the address by the specified non-negative amount.
125+
would set it to $000A.
126+
.Pp
127+
.Ql Ic DS Ar size
128+
increases the
129+
.Dq current address
130+
by
131+
.Ar size .
132+
The gap is not allocated, so smaller floating sections can later be placed there.
94133
.El
134+
.Ss Section placement
135+
A section can be placed simply by naming it (with a string).
136+
Its bank is set to the active bank, and its address to the
137+
.Dq current address .
138+
Any constraints the section already possesses (whether from earlier in the linker script, or from the object files being linked) must be consistent with what the linker script specifies: the section's type must match, the section's bank number (if set) must match the active bank, etc.
139+
In particular, if the section has an alignment constraint, the address at which it is placed by the linker script must obey that constraint; otherwise, an error will occur.
95140
.Pp
96-
.Sy Note :
97-
The bank, alignment, address and type of sections can be specified both in the source code and in the linker script.
98-
For a section to be able to be placed with the linker script, the bank, address and alignment must be left unassigned in the source code or be compatible with what is specified in the linker script.
99-
For example,
100-
.Ql ALIGN[8]
101-
in the source code is compatible with
102-
.Ql ORG $F00
103-
in the linker script.
141+
After a section is placed, the
142+
.Dq current address
143+
is increased by the section's size.
144+
This must not increase it past the end of the active memory region.
145+
.Pp
146+
The section must have been defined in the object files being linked, unless the section name is followed by the keyword
147+
.Ic OPTIONAL .
148+
.Sh EXAMPLES
149+
.Bd -literal -offset indent
150+
; This line contains only a comment
151+
ROMX $F ; start a bank
152+
"Some functions" ; a section name
153+
ALIGN 8 ; a directive
154+
"Some \e"array\e""
155+
156+
WRAMX 2 ; start another bank
157+
org $d123 ; another directive
158+
"Some variables"
159+
.Ed
104160
.Sh SEE ALSO
105161
.Xr rgbasm 1 ,
106162
.Xr rgbasm 5 ,

0 commit comments

Comments
 (0)