llvm.org GIT mirror llvm / 2b8506b
Add info to SourceLevelDebugging about CodeView Adds some discussion of the nature of the format, and some developer docs on how to work with it in LLVM. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@272057 91177308-0d34-0410-b5e6-96231b3b80d8 Reid Kleckner 3 years ago
1 changed file(s) with 78 addition(s) and 5 deletion(s). Raw diff Collapse all Expand all
6262 user a relationship between generated code and the original program source
6363 code.
6464
65 Currently, debug information is consumed by DwarfDebug to produce dwarf
66 information used by the gdb debugger. Other targets could use the same
67 information to produce stabs or other debug forms.
65 Currently, there are two backend consumers of debug info: DwarfDebug and
66 CodeViewDebug. DwarfDebug produces DWARF sutable for use with GDB, LLDB, and
67 other DWARF-based debuggers. :ref:`CodeViewDebug ` produces CodeView,
68 the Microsoft debug info format, which is usable with Microsoft debuggers such
69 as Visual Studio and WinDBG. LLVM's debug information format is mostly derived
70 from and inspired by DWARF, but it is feasible to translate into other target
71 debug info formats such as STABS.
6872
6973 It would also be reasonable to use debug information to feed profiling tools
7074 for analysis of generated code, or, tools for reconstructing the original
7175 source from generated code.
72
73 TODO - expound a bit more.
7476
7577 .. _intro_debugopt:
7678
13321334 * "``.apple_namespaces``" -> "``__apple_namespac``" (16 character limit)
13331335 * "``.apple_objc``" -> "``__apple_objc``"
13341336
1337 .. _codeview:
1338
1339 CodeView Debug Info Format
1340 ==========================
1341
1342 LLVM supports emitting CodeView, the Microsoft debug info format, and this
1343 section describes the design and implementation of that support.
1344
1345 Format Background
1346 -----------------
1347
1348 CodeView as a format is clearly oriented around C++ debugging, and in C++, the
1349 majority of debug information tends to be type information. Therefore, the
1350 overriding design constraint of CodeView is the separation of type information
1351 from other "symbol" information so that type information can be efficiently
1352 merged across translation units. Both type information and symbol information is
1353 generally stored as a sequence of records, where each record begins with a
1354 16-bit record size and a 16-bit record kind.
1355
1356 Type information is usually stored in the ``.debug$T`` section of the object
1357 file. All other debug info, such as line info, string table, symbol info, and
1358 inlinee info, is stored in one or more ``.debug$S`` sections. There may only be
1359 one ``.debug$T`` section per object file, since all other debug info refers to
1360 it. If a PDB (enabled by the ``/Zi`` MSVC option) was used during compilation,
1361 the ``.debug$T`` section will contain only an ``LF_TYPESERVER2`` record pointing
1362 to the PDB. When using PDBs, symbol information appears to remain in the object
1363 file ``.debug$S`` sections.
1364
1365 Type records are referred to by their index, which is the number of records in
1366 the stream before a given record plus ``0x1000``. Many common basic types, such
1367 as the basic integral types and unqualified pointers to them, are represented
1368 using type indices less than ``0x1000``. Such basic types are built in to
1369 CodeView consumers and do not require type records.
1370
1371 Each type record may only contain type indices that are less than its own type
1372 index. This ensures that the graph of type stream references is acyclic. While
1373 the source-level type graph may contain cycles through pointer types (consider a
1374 linked list struct), these cycles are removed from the type stream by always
1375 referring to the forward declaration record of user-defined record types. Only
1376 "symbol" records in the ``.debug$S`` streams may refer to complete,
1377 non-forward-declaration type records.
1378
1379 Working with CodeView
1380 ---------------------
1381
1382 These are instructions for some common tasks for developers working to improve
1383 LLVM's CodeView support. Most of them revolve around using the CodeView dumper
1384 embedded in ``llvm-readobj``.
1385
1386 * Testing MSVC's output::
1387
1388 $ cl -c -Z7 foo.cpp # Use /Z7 to keep types in the object file
1389 $ llvm-readobj -codeview foo.obj
1390
1391 * Getting LLVM IR debug info out of Clang::
1392
1393 $ clang -g -gcodeview --target=x86_64-windows-msvc foo.cpp -S -emit-llvm
1394
1395 Use this to generate LLVM IR for LLVM test cases.
1396
1397 * Generate and dump CodeView from LLVM IR metadata::
1398
1399 $ llc foo.ll -filetype=obj -o foo.obj
1400 $ llvm-readobj -codeview foo.obj > foo.txt
1401
1402 Use this pattern in lit test cases and FileCheck the output of llvm-readobj
1403
1404 Improving LLVM's CodeView support is a process of finding interesting type
1405 records, constructing a C++ test case that makes MSVC emit those records,
1406 dumping the records, understanding them, and then generating equivalent records
1407 in LLVM's backend.