<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Jun 7, 2016 at 1:27 PM, Reid Kleckner via llvm-commits <span dir="ltr"><<a href="mailto:llvm-commits@lists.llvm.org" target="_blank">llvm-commits@lists.llvm.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Author: rnk<br>
Date: Tue Jun  7 15:27:30 2016<br>
New Revision: 272057<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=272057&view=rev" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project?rev=272057&view=rev</a><br>
Log:<br>
Add info to SourceLevelDebugging about CodeView<br>
<br>
Adds some discussion of the nature of the format, and some developer<br>
docs on how to work with it in LLVM.<br>
<br>
Modified:<br>
    llvm/trunk/docs/SourceLevelDebugging.rst<br>
<br>
Modified: llvm/trunk/docs/SourceLevelDebugging.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/SourceLevelDebugging.rst?rev=272057&r1=272056&r2=272057&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/SourceLevelDebugging.rst?rev=272057&r1=272056&r2=272057&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/docs/SourceLevelDebugging.rst (original)<br>
+++ llvm/trunk/docs/SourceLevelDebugging.rst Tue Jun  7 15:27:30 2016<br>
@@ -63,16 +63,18 @@ away during the compilation process.  Th<br>
 user a relationship between generated code and the original program source<br>
 code.<br>
<br>
-Currently, debug information is consumed by DwarfDebug to produce dwarf<br>
-information used by the gdb debugger.  Other targets could use the same<br>
-information to produce stabs or other debug forms.<br>
+Currently, there are two backend consumers of debug info: DwarfDebug and<br>
+CodeViewDebug. DwarfDebug produces DWARF sutable for use with GDB, LLDB, and<br>
+other DWARF-based debuggers. :ref:`CodeViewDebug <codeview>` produces CodeView,<br>
+the Microsoft debug info format, which is usable with Microsoft debuggers such<br>
+as Visual Studio and WinDBG. LLVM's debug information format is mostly derived<br>
+from and inspired by DWARF, but it is feasible to translate into other target<br>
+debug info formats such as STABS.<br></blockquote><div><br></div><div>Not sure if it might be better to talk about this more abstractly, since this is the lang ref - rather than talking about the implementation details of LLVM (CodeViewDebug and DwarfDebug) just talk about "can be used to generate CodeView information or DWARF information", etc.<br><br>& the last sentence seems strange "mostly for DWARF, but feasible to implement STABS" - when the rest of the paragraph has talked about an existing concrete/implemented other format in the form of CodeView.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
 It would also be reasonable to use debug information to feed profiling tools<br>
 for analysis of generated code, or, tools for reconstructing the original<br>
 source from generated code.<br>
<br>
-TODO - expound a bit more.<br>
-<br>
 .. _intro_debugopt:<br>
<br>
 Debugging optimized code<br>
@@ -1333,3 +1335,74 @@ names as follows:<br>
 * "``.apple_namespaces``" -> "``__apple_namespac``" (16 character limit)<br>
 * "``.apple_objc``" -> "``__apple_objc``"<br>
<br>
+.. _codeview:<br>
+<br>
+CodeView Debug Info Format<br>
+==========================<br>
+<br>
+LLVM supports emitting CodeView, the Microsoft debug info format, and this<br>
+section describes the design and implementation of that support.<br>
+<br>
+Format Background<br>
+-----------------<br>
+<br>
+CodeView as a format is clearly oriented around C++ debugging, and in C++, the<br>
+majority of debug information tends to be type information. Therefore, the<br>
+overriding design constraint of CodeView is the separation of type information<br>
+from other "symbol" information so that type information can be efficiently<br>
+merged across translation units. Both type information and symbol information is<br>
+generally stored as a sequence of records, where each record begins with a<br>
+16-bit record size and a 16-bit record kind.<br>
+<br>
+Type information is usually stored in the ``.debug$T`` section of the object<br>
+file.  All other debug info, such as line info, string table, symbol info, and<br>
+inlinee info, is stored in one or more ``.debug$S`` sections. There may only be<br>
+one ``.debug$T`` section per object file, since all other debug info refers to<br>
+it. If a PDB (enabled by the ``/Zi`` MSVC option) was used during compilation,<br>
+the ``.debug$T`` section will contain only an ``LF_TYPESERVER2`` record pointing<br>
+to the PDB. When using PDBs, symbol information appears to remain in the object<br>
+file ``.debug$S`` sections.<br>
+<br>
+Type records are referred to by their index, which is the number of records in<br>
+the stream before a given record plus ``0x1000``. Many common basic types, such<br>
+as the basic integral types and unqualified pointers to them, are represented<br>
+using type indices less than ``0x1000``. Such basic types are built in to<br>
+CodeView consumers and do not require type records.<br>
+<br>
+Each type record may only contain type indices that are less than its own type<br>
+index. This ensures that the graph of type stream references is acyclic. While<br>
+the source-level type graph may contain cycles through pointer types (consider a<br>
+linked list struct), these cycles are removed from the type stream by always<br>
+referring to the forward declaration record of user-defined record types. Only<br>
+"symbol" records in the ``.debug$S`` streams may refer to complete,<br>
+non-forward-declaration type records.<br>
+<br>
+Working with CodeView<br>
+---------------------<br>
+<br>
+These are instructions for some common tasks for developers working to improve<br>
+LLVM's CodeView support. Most of them revolve around using the CodeView dumper<br>
+embedded in ``llvm-readobj``.<br>
+<br>
+* Testing MSVC's output::<br>
+<br>
+    $ cl -c -Z7 foo.cpp # Use /Z7 to keep types in the object file<br>
+    $ llvm-readobj -codeview foo.obj<br>
+<br>
+* Getting LLVM IR debug info out of Clang::<br>
+<br>
+    $ clang -g -gcodeview --target=x86_64-windows-msvc foo.cpp -S -emit-llvm<br>
+<br>
+  Use this to generate LLVM IR for LLVM test cases.<br>
+<br>
+* Generate and dump CodeView from LLVM IR metadata::<br>
+<br>
+    $ llc foo.ll -filetype=obj -o foo.obj<br>
+    $ llvm-readobj -codeview foo.obj > foo.txt<br>
+<br>
+  Use this pattern in lit test cases and FileCheck the output of llvm-readobj<br>
+<br>
+Improving LLVM's CodeView support is a process of finding interesting type<br>
+records, constructing a C++ test case that makes MSVC emit those records,<br>
+dumping the records, understanding them, and then generating equivalent records<br>
+in LLVM's backend.<br>
<br>
<br>
_______________________________________________<br>
llvm-commits mailing list<br>
<a href="mailto:llvm-commits@lists.llvm.org">llvm-commits@lists.llvm.org</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits" rel="noreferrer" target="_blank">http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits</a><br>
</blockquote></div><br></div></div>