1=====================================
2CodeView Symbol Records
3=====================================
4
5
6.. contents::
7   :local:
8
9.. _symbols_intro:
10
11Introduction
12============
13
14This document describes the usage and serialization format of the various
15CodeView symbol records that LLVM understands.  Like
16:doc:`CodeView Type Records <CodeViewTypes>`, we describe only the important
17types which are generated by modern C++ toolchains.
18
19Record Categories
20=================
21
22Symbol records share one major similarity with :doc:`type records <CodeViewTypes>`:
23They start with the same :ref:`record prefix <leaf_types>`, which we will not describe
24again (refer to the previous link for a description).  As a result of this, a sequence
25of symbol records can be processed with largely the same code as that which processes
26type records.  There are several important differences between symbol and type records:
27
28* Symbol records only appear in the :doc:`PublicStream`, :doc:`GlobalStream`, and
29  :doc:`Module Info Streams <ModiStream>`.
30* Type records only appear in the :doc:`TPI & IPI streams <TpiStream>`.
31* While types are referenced from other CodeView records via :ref:`type indices <type_indices>`,
32  symbol records are referenced by the byte offset of the record in the stream that it appears
33  in.
34* Types can reference types (via type indices), and symbols can reference both types (via type
35  indices) and symbols (via offsets), but types can never reference symbols.
36* There is no notion of :ref:`Leaf Records <leaf_types>` and :ref:`Member Records <member_types>`
37  as there are with types.  Every symbol record describes is own length.
38* Certain special symbol records begin a "scope".  For these records, all following records
39  up until the next ``S_END`` record are "children" of this symbol record.  For example,
40  given a symbol record which describes a certain function, all local variables of this
41  function would appear following the function up until the corresponding ``S_END`` record.
42
43Finally, there are three general categories of symbol record, grouped by where they are legal
44to appear in a PDB file.  Public Symbols (which appear only in the
45:doc:`publics stream <PublicStream>`), Global Symbols (which appear only in the
46:doc:`globals stream <GlobalStream>`) and module symbols (which appear in the
47:doc:`module info stream <ModiStream>`).
48
49
50.. _public_symbols:
51
52Public Symbols
53--------------
54
55Public symbols are the CodeView equivalent of DWARF ``.debug_pubnames``.  There
56is one public symbol record for every function or variable in the program that
57has a mangled name.  The :doc:`Publics Stream <PublicStream>`, which contains these
58records, additionally contains a hash table that allows one to quickly locate a
59record by mangled name.
60
61S_PUB32 (0x110e)
62^^^^^^^^^^^^^^^^
63
64There is only type of public symbol, an ``S_PUB32`` which describes a mangled
65name, a flag indicating what kind of symbol it is (e.g. function, variable), and
66the symbol's address.  The :ref:`dbi_section_map_substream` of the
67:doc:`DBI Stream <DbiStream>` can be consulted to determine what module this address
68corresponds to, and from there that module's :doc:`module debug stream <ModiStream>`
69can be consulted to locate full information for the symbol with the given address.
70
71.. _global_symbols:
72
73Global Symbols
74--------------
75
76While there is one :ref:`public symbol <public_symbols>` for every symbol in the
77program with `external` linkage, there is one global symbol for every symbol in the
78program with linkage (including internal linkage).  As a result, global symbols do
79not describe a mangled name *or* an address, since symbols with internal linkage
80need not have any mangling at all, and also may not have an address.  Thus, all
81global symbols simply refer directly to the full symbol record via a module/offset
82combination.
83
84Similarly to :ref:`public symbols <public_symbols>`, all global symbols are contained
85in a single :doc:`Globals Stream <GlobalStream>`, which contains a hash table mapping
86fully qualified name to the corresponding record in the globals stream (which as
87mentioned, then contains information allowing one to locate the full record in the
88corresponding module symbol stream).
89
90Note that a consequence and limitation of this design is that program-wide lookup
91by anything other than an exact textually matching fully-qualified name of whatever
92the compiler decided to emit is impractical.  This differs from DWARF, where even
93though we don't necessarily have O(1) lookup by basename within a given scope (including
94O(1) scope, we at least have O(n) access within a given scope).
95
96.. important::
97   Program-wide lookup of names by anything other than an exact textually matching fully
98   qualified name is not possible.
99
100
101S_GDATA32
102^^^^^^^^^^
103
104S_GTHREAD32 (0x1113)
105^^^^^^^^^^^^^^^^^^^^
106
107S_PROCREF (0x1125)
108^^^^^^^^^^^^^^^^^^
109
110S_LPROCREF (0x1127)
111^^^^^^^^^^^^^^^^^^^
112
113S_GMANDATA (0x111d)
114^^^^^^^^^^^^^^^^^^^
115
116.. _module_symbols:
117
118Module Symbols
119--------------
120
121S_END (0x0006)
122^^^^^^^^^^^^^^
123
124S_FRAMEPROC (0x1012)
125^^^^^^^^^^^^^^^^^^^^
126
127S_OBJNAME (0x1101)
128^^^^^^^^^^^^^^^^^^
129
130S_THUNK32 (0x1102)
131^^^^^^^^^^^^^^^^^^
132
133S_BLOCK32 (0x1103)
134^^^^^^^^^^^^^^^^^^
135
136S_LABEL32 (0x1105)
137^^^^^^^^^^^^^^^^^^
138
139S_REGISTER (0x1106)
140^^^^^^^^^^^^^^^^^^^
141
142S_BPREL32 (0x110b)
143^^^^^^^^^^^^^^^^^^
144
145S_LPROC32 (0x110f)
146^^^^^^^^^^^^^^^^^^
147
148S_GPROC32 (0x1110)
149^^^^^^^^^^^^^^^^^^
150
151S_REGREL32 (0x1111)
152^^^^^^^^^^^^^^^^^^^
153
154S_COMPILE2 (0x1116)
155^^^^^^^^^^^^^^^^^^^
156
157S_UNAMESPACE (0x1124)
158^^^^^^^^^^^^^^^^^^^^^
159
160S_TRAMPOLINE (0x112c)
161^^^^^^^^^^^^^^^^^^^^^
162
163S_SECTION (0x1136)
164^^^^^^^^^^^^^^^^^^
165
166S_COFFGROUP (0x1137)
167^^^^^^^^^^^^^^^^^^^^
168
169S_EXPORT (0x1138)
170^^^^^^^^^^^^^^^^^
171
172S_CALLSITEINFO (0x1139)
173^^^^^^^^^^^^^^^^^^^^^^^
174
175S_FRAMECOOKIE (0x113a)
176^^^^^^^^^^^^^^^^^^^^^^
177
178S_COMPILE3 (0x113c)
179^^^^^^^^^^^^^^^^^^^
180
181S_ENVBLOCK (0x113d)
182^^^^^^^^^^^^^^^^^^^
183
184S_LOCAL (0x113e)
185^^^^^^^^^^^^^^^^
186
187S_DEFRANGE (0x113f)
188^^^^^^^^^^^^^^^^^^^
189
190S_DEFRANGE_SUBFIELD (0x1140)
191^^^^^^^^^^^^^^^^^^^^^^^^^^^^
192
193S_DEFRANGE_REGISTER (0x1141)
194^^^^^^^^^^^^^^^^^^^^^^^^^^^^
195
196S_DEFRANGE_FRAMEPOINTER_REL (0x1142)
197^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
198
199S_DEFRANGE_SUBFIELD_REGISTER (0x1143)
200^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
201
202S_DEFRANGE_FRAMEPOINTER_REL_FULL_SCOPE (0x1144)
203^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
204
205S_DEFRANGE_REGISTER_REL (0x1145)
206^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
207
208S_LPROC32_ID (0x1146)
209^^^^^^^^^^^^^^^^^^^^^
210
211S_GPROC32_ID (0x1147)
212^^^^^^^^^^^^^^^^^^^^^
213
214S_BUILDINFO (0x114c)
215^^^^^^^^^^^^^^^^^^^^
216
217S_INLINESITE (0x114d)
218^^^^^^^^^^^^^^^^^^^^^
219
220S_INLINESITE_END (0x114e)
221^^^^^^^^^^^^^^^^^^^^^^^^^
222
223S_PROC_ID_END (0x114f)
224^^^^^^^^^^^^^^^^^^^^^^
225
226S_FILESTATIC (0x1153)
227^^^^^^^^^^^^^^^^^^^^^
228
229S_LPROC32_DPC (0x1155)
230^^^^^^^^^^^^^^^^^^^^^^
231
232S_LPROC32_DPC_ID (0x1156)
233^^^^^^^^^^^^^^^^^^^^^^^^^
234
235S_CALLEES (0x115a)
236^^^^^^^^^^^^^^^^^^
237
238S_CALLERS (0x115b)
239^^^^^^^^^^^^^^^^^^
240
241S_HEAPALLOCSITE (0x115e)
242^^^^^^^^^^^^^^^^^^^^^^^^
243
244S_FASTLINK (0x1167)
245^^^^^^^^^^^^^^^^^^^
246
247S_INLINEES (0x1168)
248^^^^^^^^^^^^^^^^^^^
249
250.. _module_and_global_symbols:
251
252Symbols which can go in either/both of the module info stream & global stream
253-----------------------------------------------------------------------------
254
255S_CONSTANT (0x1107)
256^^^^^^^^^^^^^^^^^^^
257
258S_UDT (0x1108)
259^^^^^^^^^^^^^^
260
261S_LDATA32 (0x110c)
262^^^^^^^^^^^^^^^^^^
263
264S_LTHREAD32 (0x1112)
265^^^^^^^^^^^^^^^^^^^^
266
267S_LMANDATA (0x111c)
268^^^^^^^^^^^^^^^^^^^
269
270S_MANCONSTANT (0x112d)
271^^^^^^^^^^^^^^^^^^^^^^
272
273