1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
//! Small helpers shared by the format backends and the layout passes.
//!
//! Every item here was duplicated across two or more modules before it landed
//! in this one. Nothing format-specific belongs here: these are the byte,
//! string-table and alignment primitives the ELF, Mach-O and COFF paths all
//! reach for.
use ;
use Pod;
use crate::;
/// An input list this long is opened in parallel; a shorter one is opened
/// on the calling thread.
///
/// Opening is dominated by kernel path resolution, which scales across
/// threads (the dentry cache is read under RCU), and a large link opens
/// thousands of files before any other work can start. Below the threshold
/// the fan-out costs more than it earns -- the same trade [`crate::pool`]
/// measures for the link passes -- and this runs before the pool there is
/// sized, so a small link must not be the thing that spins the global pool
/// up. At roughly 30us per open, a hundred files are three milliseconds:
/// the largest list still opened serially costs less than the noise floor
/// of the whole link.
const PARALLEL_OPEN: usize = 100;
/// Makes every input readable, in order: a path is mapped, caller-supplied
/// bytes are borrowed or realigned. See [`Input::open`].
///
/// The file opens fan out; the memory mappings do not. Every `mmap` takes
/// the process's address-space lock for writing, so mapping from many
/// threads buys spin contention rather than time -- measured once as 5% of
/// total CPU in `osq_lock` for a 1.5% wall-clock return. Opening scales,
/// mapping is cheap and serial: about 5us of the 30us an open-and-map pair
/// costs.
///
/// Errors keep input order: the parallel phase records per-input results
/// and the sequential fold below reports the first failure, so a bad input
/// names the same file whichever thread reached it first.
/// Writes the linked image to `output` with executable permissions.
///
/// The image lands under a temporary sibling first and is renamed into
/// place only once every byte is on disk, the same contract the ELF
/// writer's `OutputFile` honours: a build watcher -- or a build system
/// globbing the output directory -- never sees a half-written
/// executable, and a full disk leaves the previous output standing
/// rather than a truncated one wearing its name.
/// The mode a produced executable is published with: everything, less what
/// the process's umask withholds.
///
/// A fixed `0o755` is not "executable permissions", it is a decision to
/// override the one setting whose entire job is to make that decision. Under
/// `umask 077` every other linker produces `0o700` and xold produced a
/// world-readable, world-executable image -- on a build of something the user
/// had asked the system to keep to themselves.
/// The process umask, read once.
/// Reads the umask from `/proc/self/status`, which Linux has reported since
/// 4.7.
///
/// There is no way to read it through libc without also setting it, and
/// setting it here -- even to put it straight back -- would race every other
/// thread in the process that creates a file, which for a linker used as a
/// library is not a race it is entitled to run. Reading is the only safe
/// answer.
///
/// The fallback when the line is absent is `0o022`, the near-universal
/// default; it is also what the fixed `0o755` assumed, so nothing regresses
/// where the file cannot be read.
/// Writes one `Pod` struct into `image` at `off`.
///
/// Returns the offset one past the last byte written.
///
/// An out-of-range offset is recorded rather than ignored. Callers size the
/// image from the layout, so the branch cannot run for a correctly sized
/// image; should that ever stop holding, a silent truncation would be
/// indistinguishable from a clean link.
/// Whether any [`write_pod`] fell outside the image this process has built.
///
/// A process-wide flag rather than a return value: the eighteen call sites
/// serialise headers and directory entries in sequence, and threading a
/// `Result` through each would say the same thing eighteen times over. The
/// writers ask once, at the end, and refuse to publish an image that any part
/// of failed to reach -- so a sizing bug ends the link instead of shipping a
/// truncated file.
static TRUNCATED: AtomicBool = new;
/// Records that a write fell outside the image.
/// Whether a write fell outside the image, clearing the flag for the next
/// link. Called once per image, after everything is serialised.
/// Aborts the link if any [`write_pod`] fell outside the image.
///
/// The format writers call this once, after serialising everything, instead of
/// threading the same `Result` through every header write. See
/// [`took_truncated_write`] for why the flag is process-wide.
/// The page size every output format aligns segments and sections to.
pub const PAGE: u64 = 0x1000;
/// Rounds `value` up to a multiple of `align` (no effect for `align <= 1`).
///
/// Saturating rather than wrapping: a value within `align` of `u64::MAX` has
/// no next multiple, and answering with a small number would place a section
/// at the bottom of the address space. Every caller here is a placement cursor
/// that only ever moves forward, so saturating keeps that invariant while
/// wrapping would break it. Inputs that could reach the boundary are rejected
/// where they enter -- see [`check_align`] -- so this is the backstop rather
/// than the check.
/// Rejects an input section's `sh_addralign` that alignment arithmetic cannot
/// use.
///
/// A power of two is what the field means: the rounding is a mask, and a mask
/// only describes the alignment it was derived from when exactly one bit is
/// set. A non-power-of-two silently produced a mask for the next power below,
/// so a section declaring 24 was aligned to 8 with nothing said.
///
/// The bound is the largest alignment a linker has any use for. Nothing needs
/// more than a page-table entry's worth, and a value near `u64::MAX` is an
/// arithmetic hazard rather than a request: it exists in a malformed or
/// hostile input, not in an object a compiler wrote.
/// The largest `sh_addralign` this linker accepts: one gigabyte, which is far
/// past anything a target's ABI asks for and far short of where the rounding
/// arithmetic gets interesting.
const MAX_ALIGN: u64 = 1 << 30;
/// Rounds `value` up to a multiple of `align`, in the 32-bit widths the PE
/// section and file alignments use.
/// Returns the bytes of a NUL-terminated string starting at `offset`.
///
/// The string stops at the first NUL or the end of the table. A missing or
/// out-of-range offset yields an empty slice rather than an error, matching how
/// linkers tolerate stray string-table offsets.
/// Trims a fixed-size name cell at the first NUL. Mach-O segment/section names
/// and PE section names are stored NUL-padded in a fixed-width field.
/// Pads `name` with NULs into an `N`-byte cell, truncating overlong names.
/// The inverse of [`trim_nul`]: PE uses `N = 8`, Mach-O `N = 16`.
/// Appends `value` as a little-endian signed 32-bit integer. The relative
/// offsets within one image always fit a signed 32-bit slot; truncation only
/// discards the high bits the loader contract never uses.
/// Appends `value` as a little-endian unsigned 32-bit integer.
/// Whether `name` is a valid C identifier.
///
/// A section whose name is one is special: the linker is expected to bound it
/// with `__start_NAME` and `__stop_NAME` (see [`crate::startstop`]), so such a
/// section can be reached without any relocation naming it and must never be
/// folded onto another ([`crate::icf`]). A name containing a dot is never an
/// identifier, which is what makes the check cheap for the `.text.foo` shape
/// almost every input section has.
/// Renders symbol-table bytes for a diagnostic, replacing invalid UTF-8.