Skip to content
← Back

src/ir/emitter/srm_pdb_builder.ghul

1
@@IF.dotnet()
2
3
namespace IR.Emitter is
4
use System.Reflection.Metadata.BlobBuilder
5
use System.Reflection.Metadata.BlobContentId
6
use System.Reflection.Metadata.DocumentHandle
7
use System.Reflection.Metadata.Ecma335.MetadataBuilder
8
use System.Reflection.Metadata.Ecma335.PortablePdbBuilder
9
10
// One source position the debugger or a coverage tool can stop at,
11
// paired with the instruction offset it starts at.
12
class SRM_SEQUENCE_POINT(
13
il_offset: int,
14
file_name: string,
15
start_line: int,
16
start_column: int,
17
end_line: int,
18
end_column: int
19
)
20
21
// A run of instructions an `@IL.output` pragma marks. The binary back
22
// end records one per marked statement and carries them out of the
23
// method as a custom attribute, which the IL test runner reads back to
24
// slice the disassembly to just the statement's instructions. The
25
// sequence number is compilation-global, so a test marking statements
26
// in more than one method can rebuild their source order.
27
class SRM_IL_OUTPUT_RANGE(
28
path: string,
29
start_offset: int,
30
end_offset: int,
31
sequence: int
32
)
33
34
// Builds the portable PDB that sits beside the emitted assembly.
35
//
36
// A PDB is its own metadata file with its own tables, so this holds
37
// a second MetadataBuilder rather than adding to the assembly's.
38
// The one hard coupling between them is MethodDebugInformation:
39
// its rows are not looked up by key, they are read positionally
40
// against MethodDef, so row N here has to describe method N there.
41
// Nothing checks - a missing row shifts every method after it onto
42
// another method's line numbers, which reads as a compiler that
43
// emits plausible but wrong debug info rather than as a broken
44
// file. `add_method_debug_information` is therefore called once per
45
// MethodDef row from the one place that adds them, including for
46
// the methods that have no sequence points at all.
47
class SRM_PDB_BUILDER is
48
_metadata: MetadataBuilder
49
_documents: Collections.MAP[string, DocumentHandle]
50
51
init() is
52
_metadata = MetadataBuilder(0, 0, 0, 0)
53
_documents = Collections.MAP[string, DocumentHandle]()
54
si
55
56
_EMPTY_HASH: ubyte[] static => []
57
58
_document(file_name: string) -> DocumentHandle is
59
let existing: DocumentHandle mut
60
61
if _documents.try_get_value(file_name, existing ref) then
62
return existing
63
fi
64
65
// No hash and no language: a hash commits the PDB to one
66
// byte-for-byte revision of the source, which is what a
67
// debugger checks before binding a breakpoint, and the
68
// compiler does not keep the bytes it read by the time the
69
// assembly is written. Line lookup and coverage attribution
70
// read the name and the sequence points, and need neither.
71
let handle =
72
_metadata.add_document(
73
_metadata.get_or_add_document_name(file_name),
74
_[System.Reflection.Metadata.GuidHandle],
75
_metadata.get_or_add_blob(_EMPTY_HASH),
76
_[System.Reflection.Metadata.GuidHandle])
77
78
_documents[file_name] = handle
79
80
return handle
81
si
82
83
// One row, whether or not there is anything to say - see the
84
// positional coupling above. A method with no sequence points
85
// (an abstract declaration, a compiler-synthesised member, any
86
// method at all in a non-debug build) gets an empty row.
87
add_method_debug_information(points: Collections.List[SRM_SEQUENCE_POINT]?) is
88
if !points? \/ points.count == 0 then
89
_metadata.add_method_debug_information(
90
_[DocumentHandle], _[System.Reflection.Metadata.BlobHandle])
91
92
return
93
fi
94
95
let initial_document = _document(points[0].file_name)
96
97
_metadata.add_method_debug_information(
98
initial_document,
99
_metadata.get_or_add_blob(_sequence_point_blob(points, initial_document)))
100
si
101
102
// The sequence-point blob, as ECMA-335 II.24.2.1 defines it:
103
// a header naming the method's local signature, then one record
104
// per point, each expressed as a delta from the one before so
105
// the common case costs a handful of bytes.
106
//
107
// The first record carries absolute values; every later one
108
// carries deltas, and its IL-offset delta must be non-zero,
109
// because a zero there is the marker for a document-change
110
// record instead.
111
_sequence_point_blob(
112
points: Collections.List[SRM_SEQUENCE_POINT],
113
initial_document: DocumentHandle
114
) -> ubyte[] is
115
let buffer = BlobBuilder(32)
116
117
// Local signature. The back end emits no StandAloneSig row
118
// for a body's locals, so there is none to name.
119
buffer.write_compressed_integer(0)
120
121
let previous mut = _[SRM_SEQUENCE_POINT?]
122
let current_document mut = initial_document
123
124
for point in points do
125
let document = _document(point.file_name)
126
127
if !(document =~ current_document) then
128
// A document-change record: the zero IL-offset
129
// delta that no ordinary record can carry, then the
130
// document being switched to.
131
//
132
// It changes which document the records after it
133
// belong to and nothing else. The deltas keep
134
// running from the last real sequence point, so the
135
// record following it is still a delta rather than
136
// absolute - resetting the baseline here would
137
// desynchronise every offset and line after it.
138
buffer.write_compressed_integer(0)
139
buffer.write_compressed_integer(
140
System.Reflection.Metadata.Ecma335.MetadataTokens.get_row_number(
141
cast System.Reflection.Metadata.EntityHandle(document)))
142
143
current_document = document
144
fi
145
146
let delta_lines = point.end_line - point.start_line
147
let delta_columns = point.end_column - point.start_column
148
149
if let seen = previous then
150
buffer.write_compressed_integer(point.il_offset - seen.il_offset)
151
else
152
buffer.write_compressed_integer(point.il_offset)
153
fi
154
155
buffer.write_compressed_integer(delta_lines)
156
157
// On a point that begins and ends on one line the
158
// column delta is that line's width, which cannot be
159
// negative, so it is unsigned. Across lines the end
160
// column can fall to the left of the start column, so
161
// it is signed.
162
if delta_lines == 0 then
163
buffer.write_compressed_integer(delta_columns)
164
else
165
buffer.write_compressed_signed_integer(delta_columns)
166
fi
167
168
if let seen = previous then
169
buffer.write_compressed_signed_integer(
170
point.start_line - seen.start_line)
171
buffer.write_compressed_signed_integer(
172
point.start_column - seen.start_column)
173
else
174
buffer.write_compressed_integer(point.start_line)
175
buffer.write_compressed_integer(point.start_column)
176
fi
177
178
previous = point
179
od
180
181
return buffer.to_array()
182
si
183
184
// Writes the PDB and hands back the identity the assembly's
185
// debug directory has to name for a runtime to pair the two.
186
// The serialized PDB, for a caller that wants the bytes rather
187
// than a file - reading them back through a metadata reader is
188
// how the blob encoding above is tested.
189
serialize(
190
blob: BlobBuilder,
191
type_system_row_counts: System.Collections.Immutable.ImmutableArray[int],
192
entry_point: System.Reflection.Metadata.MethodDefinitionHandle,
193
content_id_provider: (Collections.Iterable[System.Reflection.Metadata.Blob]) -> BlobContentId
194
) -> BlobContentId =>
195
PortablePdbBuilder(
196
_metadata, type_system_row_counts, entry_point, content_id_provider)
197
.serialize(blob)
198
199
write_to(
200
path: string,
201
type_system_row_counts: System.Collections.Immutable.ImmutableArray[int],
202
entry_point: System.Reflection.Metadata.MethodDefinitionHandle,
203
content_id_provider: (Collections.Iterable[System.Reflection.Metadata.Blob]) -> BlobContentId
204
) -> BlobContentId is
205
let blob = BlobBuilder(1024)
206
207
let content_id =
208
serialize(blob, type_system_row_counts, entry_point, content_id_provider)
209
210
let stream = IO.File.create(path)
211
blob.write_content_to(stream)
212
stream.close()
213
214
return content_id
215
si
216
si
217
si