rucc_object/section.rs
1//! What an object writer is given, which is a section of bytes and what the linker has to be
2//! told about them.
3//!
4//! Design: `spec/11-asm-objects-debug.md` sections 11.1 and 11.3.
5//!
6//! These types are here rather than beside the assembler that fills them in because they are what
7//! an object file is made of, and because a writer cannot depend on the thing that produces its
8//! input without the graph going the wrong way round. The assembler at layer rank 10 reaches down
9//! to these at rank 8, which is the direction `spec/18-package-layout.md` asks for.
10
11/// What a function is aligned to when nothing asked for more.
12///
13/// Sixteen because that is what every x86-64 toolchain puts a function at, and because it is what
14/// keeps the loop inside one from straddling one more cache line than it has to. Here rather than
15/// beside the assembler because the assembler pads to it and the writer records it, and two
16/// copies of one number is how the padding and the record come apart.
17pub const FUNC_ALIGN: u32 = 16;
18
19/// A text section, and what the linker has to be told about it.
20#[derive(Debug, Clone, PartialEq, Eq)]
21pub struct Text {
22 /// The instructions, in the order they were laid out.
23 pub bytes: Vec<u8>,
24 /// Where each function starts and how long it is, in the order they were written.
25 pub funcs: Vec<Extent>,
26 /// Every place in the bytes that names something the linker has to find.
27 pub relocs: Vec<Reloc>,
28 /// What the whole section has to be aligned to, which is the largest alignment any function
29 /// in it asked for.
30 ///
31 /// A function is at a fixed offset inside the section, so a function at a multiple of two
32 /// hundred and fifty six is one only if the section itself is at one. The padding between the
33 /// functions is the assembler's half of the same job and this is the linker's.
34 pub align: u32,
35}
36
37impl Default for Text {
38 fn default() -> Self {
39 Self { bytes: Vec::new(), funcs: Vec::new(), relocs: Vec::new(), align: FUNC_ALIGN }
40 }
41}
42
43/// Where one function ended up.
44///
45/// How long a function is is a fact ELF records and Mach-O has no way to, so it is handed over
46/// rather than worked out again: the writer that wants it has it and the one that does not
47/// ignores it.
48#[derive(Debug, Clone, PartialEq, Eq)]
49pub struct Extent {
50 /// The function's name, as the C program spelled it. The underscore an Apple symbol carries
51 /// is the object writer's business, not this one's.
52 pub name: String,
53 /// Where its first instruction is.
54 pub start: usize,
55 /// How many bytes of instructions it is, not counting the padding in front of the next one.
56 pub len: usize,
57}
58
59/// The variables a file defines, and what the linker has to be told about them.
60///
61/// One entry per variable rather than one section of everything, because where a variable goes is
62/// worked out from what it is and two of them that land in one section still have their own
63/// alignment, their own size and their own symbol. Putting them together is the writer's job and
64/// is the one part of it the three formats disagree about.
65#[derive(Debug, Clone, Default, PartialEq, Eq)]
66pub struct Data {
67 /// Every variable this file defines, in the order the module held them.
68 pub objects: Vec<Object>,
69}
70
71/// One global variable, laid out.
72#[derive(Debug, Clone, PartialEq, Eq)]
73pub struct Object {
74 /// Its name, as the C program spelled it. The underscore an Apple symbol carries is the
75 /// object writer's business, not this one's.
76 pub name: String,
77 /// Its image, and nothing at all when it is zero filled and the file carries none of it.
78 pub bytes: Vec<u8>,
79 /// How many bytes it occupies, which is the length of the image except when there is none.
80 pub size: u64,
81 /// What it has to be aligned to, always a power of two.
82 pub align: u64,
83 /// Which section it goes in.
84 pub place: Place,
85 /// How the linker sees the name.
86 pub binding: Binding,
87 /// Every place in its image that holds the address of a symbol, counted from the start of
88 /// the image rather than from the start of the section it lands in.
89 pub relocs: Vec<Reloc>,
90}
91
92/// Which section a variable goes in.
93///
94/// Worked out from what the variable is rather than named by it, except in the one case where the
95/// program named it. A reader who wants to know why a variable is in `.rodata` should be able to
96/// find the answer in the variable.
97#[derive(Debug, Clone, PartialEq, Eq)]
98pub enum Place {
99 /// Written to, and its image is not all zeros. `.data`.
100 Written,
101 /// Never written to, so it can go in a page the loader maps read only and every process
102 /// running the program can share. `.rodata`.
103 ReadOnly,
104 /// All zeros, so the file says how big it is and carries none of it. `.bss`.
105 Zero,
106 /// A tentative definition, which is not in a section at all: the linker is asked for that
107 /// much zeroed space and merges every definition of the name into one. `.comm`.
108 Merged,
109 /// The section the program named, from `__attribute__((section(...)))`.
110 Named(String),
111}
112
113/// How the linker sees a name.
114///
115/// Three of the five linkages the IR has, because that is how many an object file can say. Which
116/// of the two weak ones a symbol had is a fact the optimizer needs and the linker does not.
117#[derive(Debug, Clone, Copy, PartialEq, Eq)]
118pub enum Binding {
119 /// Visible to every other object, and the definition here is the definition.
120 Global,
121 /// Invisible outside this object, which is what `static` at file scope means.
122 Local,
123 /// Visible, and allowed to lose to a definition in another object.
124 Weak,
125}
126
127/// One reference to something this file does not contain.
128#[derive(Debug, Clone, PartialEq, Eq)]
129pub struct Reloc {
130 /// Where the bytes the linker writes over begin.
131 pub at: usize,
132 /// What is wanted, as the C program spelled it.
133 pub symbol: String,
134 /// What the linker is being asked for.
135 pub kind: Reference,
136 /// What to add to the distance, which is the constant the instruction already meant plus the
137 /// bytes between the hole and the end of the instruction, negated. An instruction counts from
138 /// where it ends and a relocation counts from where it starts, and this is the difference.
139 pub addend: i64,
140}
141
142/// What kind of thing a relocation is asking the linker for.
143///
144/// The first two are the distance from the end of an instruction to something, which is what every
145/// reference the code makes is, because this compiler generates position independent code and
146/// nothing else. They are told apart because the linker may answer one of them with a stub and may
147/// not answer the other one that way. The third is not a distance at all and is the only kind an
148/// image asks for, since an initializer holding the address of something holds the address itself.
149#[derive(Debug, Clone, Copy, PartialEq, Eq)]
150pub enum Reference {
151 /// A call, which the linker may satisfy with a stub that reaches further than the four bytes
152 /// would. `R_X86_64_PLT32` on ELF, and the same relocation a branch gets on the other two.
153 Call,
154 /// A datum, reached from the instruction pointer. `R_X86_64_PC32` on ELF.
155 Data,
156 /// The address itself, written into an image. `int *p = &y;` and nothing else in C.
157 Address {
158 /// How many bytes of it are written, which is the pointer width except on a target with
159 /// a narrower relocation for it. `R_X86_64_64` and `R_X86_64_32` on ELF.
160 bytes: u8,
161 },
162}