docs/PDB/CodeViewSymbols.rst

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