added intel-pt build instructions for lldb

[JDevlieghere]

Can we include this in the docs folder instead? Having READMEs spread throughout the sources isn't going to be particularly discoverable.

[zrthxn]

In D121935#3389954, @JDevlieghere wrote:

Can we include this in the docs folder instead? Having READMEs spread throughout the sources isn't going to be particularly discoverable.

Sure can. Should I also use RST instead of MD? Also which particular folder in docs?

[wallace]

Thank you very much for helping out with the documentaiton!

As Jonas said, move the file to lldb/docs/intel_pt.rst and modify the necessary bits (some CMake changes) so that the documentation eventually appears in https://lldb.llvm.org/index.html as an "Tracing with Intel PT" section under the "Testing LLDB using QEMU" section.
You can follow the format of https://lldb.llvm.org/use/qemu-testing.html for the document.

lldb/source/Plugins/Trace/intel-pt/README.md

1 ↗

(On Diff #416259)

Tracing with Intel Processor Trace (Intel PT)

2 ↗

(On Diff #416259)

Intel PT is a technology available in modern Intel CPUs that allows efficient tracing of all the instructions executed by a process. LLDB can collect traces and dump them using its symbolication stack. You can read more here https://easyperf.net/blog/2019/08/23/Intel-Processor-Trace.

3 ↗

(On Diff #416259)

Prerequisites

5 ↗

(On Diff #416259)

11 ↗

(On Diff #416259)

15 ↗

(On Diff #416259)

15–40 ↗

(On Diff #416259)

Let's keep it concise and direct

20–23 ↗

(On Diff #416259)

remove this, because you can assume the developer already knows how to build lldb

25–27 ↗

(On Diff #416259)

only keep libipt-build

42–60 ↗

(On Diff #416259)

62–81 ↗

(On Diff #416259)

Instead of these instructions, you can use the internal documentation I have for using Intel PT.

https://pastebin.com/UiJJ32uh

Copy paste it here and add the appropriate formatting as a "How to use" section :)

85–86 ↗

(On Diff #416259)

90 ↗

(On Diff #416259)

just delete this one

[zrthxn]

Switched to RST. Although I'm not very familiar with RST, I've done my best to match the existing docs. Please let me know if changes are needed.

[wallace]

Pretty nice improvement! Now you need to reference this doc from the main page. See this reference patch https://reviews.llvm.org/D82064. According to it, you need to move this doc to lldb/docs/use/intel_pt.rst and reference it from lldb/docs/index.rst.

Besides that, you should generate the documentation and make sure that the output html looks correct. I haven't done that myself, but according to https://reviews.llvm.org/D55376, you should be able to do ninja docs-lldb-html after setting as true the cmake flag -DLLVM_ENABLE_SPHINX. Then, include a screenshot of the generated documentation.

lldb/docs/intel_pt.rst

17 ↗

(On Diff #416287)

48 ↗

(On Diff #416287)

just remove this, as it's a little bit obvious

51 ↗

(On Diff #416287)

let's put this as a one liner as it's common to everyone

[zrthxn]

Here is the screenshot as well as the HTML file
The screenshot doesn't have the CSS theming...

intel_pt.html22 KBDownload

[zrthxn]

Referenced IPT doc from main page

[wallace]

lgtm

[JDevlieghere]

Please reflow the document to match the 80 column limit observed in the other docs. LGTM with that addressed.

[zrthxn]

Reflow to 80 cols

In D121935#3392593, @JDevlieghere wrote:

Please reflow the document to match the 80 column limit observed in the other docs. LGTM with that addressed.

I've tried my best to do this, it wasn't possible on some lines

[JDevlieghere]

Thanks!

lldb/docs/index.rst

.. toctree::
    use/symbolication
    use/symbols
    use/python
    use/python-reference
    use/remote
    use/qemu-testing
    use/troubleshooting
    use/links
+   use/intel_pt
 
 .. toctree::
    :hidden:
    :maxdepth: 1
    :caption: Development
 
    resources/contributing
    resources/build

lldb/docs/use/intel_pt.rst

+Tracing with Intel Processor Trace (Intel PT)
+=============================================
+
+.. contents::
+  :local:
+
+Intel PT is a technology available in modern Intel CPUs that allows efficient 
+tracing of all the instructions executed by a process. 
+LLDB can collect traces and dump them using its symbolication stack. 
+You can read more here 
+https://easyperf.net/blog/2019/08/23/Intel-Processor-Trace.
+
+Prerequisites
+-------------
+
+Confirm that your CPU supports Intel PT 
+(see https://www.intel.com/content/www/us/en/support/articles/000056730/processors.html) 
+and that your operating system is Linux.
+
+Check for the existence of this particular file on your Linux system
+:: 
+
+  $ cat /sys/bus/event_source/devices/intel_pt/type
+
+The output should be a number. Otherwise, try upgrading your kernel.
+
+
+Build Instructions
+------------------
+
+Clone and build the low level Intel PT 
+decoder library [LibIPT library](https://github.com/intel/libipt).
+:: 
+
+  $ git clone [e-mail]:intel/libipt.git
+  $ mkdir libipt-build
+  $ cmake -S libipt -B libipt-build
+  $ cd libipt-build
+  $ make
+
+This will generate a few files in the `<libipt-build>/lib` 
+and `<libipt-build>/libipt/include` directories.
+
+Configure and build LLDB with Intel PT support
+:: 
+
+  $ cmake \                
+      -DLLDB_BUILD_INTEL_PT=ON \
+      -DLIBIPT_INCLUDE_PATH="<libipt-build>/libipt/include" \
+      -DLIBIPT_LIBRARY_PATH="<libipt-build>/lib" \
+      ... other common configuration parameters 
+
+:: 
+
+  $ cd <lldb-build> && ninja lldb lldb-server # if using Ninja
+
+
+How to Use
+----------
+
+When you are debugging a process, you can turn on intel-pt tracing, 
+which will “record” all the instructions that the process will execute. 
+After turning it on, you can continue debugging, and at any breakpoint, 
+you can inspect the instruction list.
+ 
+For example:
+::
+  lldb <target>
+  > b main
+  > run
+  > process trace start # start tracing on all threads, including future ones
+  # keep debugging until you hit a breakpoint
+  
+  > thread trace dump instructions
+  # this should output something like
+
+  thread #2: tid = 2861133, total instructions = 5305673
+    libc.so.6`__GI___libc_read + 45 at read.c:25:1
+      [4962255] 0x00007fffeb64c63d    subq   $0x10, %rsp
+      [4962256] 0x00007fffeb64c641    movq   %rdi, -0x18(%rbp)
+    libc.so.6`__GI___libc_read + 53 [inlined] __libc_read at read.c:26:10
+      [4962257] 0x00007fffeb64c645    callq  0x7fffeb66b640            ; __libc_enable_asynccancel
+    libc.so.6`__libc_enable_asynccancel
+      [4962258] 0x00007fffeb66b640    movl   %fs:0x308, %eax
+    libc.so.6`__libc_enable_asynccancel + 8
+      [4962259] 0x00007fffeb66b648    movl   %eax, %r11d
+
+  # you can keep pressing ENTER to see more and more instructions
+ 
+The number between brackets is the instruction index, 
+and by default the current thread will be picked.
+ 
+Configuring the trace size
+--------------------------
+ 
+The CPU stores the instruction list in a compressed format in a ring buffer, 
+which keeps the latest information. 
+By default, LLDB uses a buffer of 4KB per thread, 
+but you can change it by running. 
+The size must be a power of 2 and at least 4KB.
+::
+  thread trace start all -s <size_in_bytes>
+ 
+For reference, a 1MB trace buffer can easily store around 5M instructions.
+ 
+Printing more instructions
+--------------------------
+ 
+If you want to dump more instructions at a time, you can run
+::
+  thread trace dump instructions -c <count>
+ 
+Printing the instructions of another thread
+-------------------------------------------
+
+By default the current thread will be picked when dumping instructions, 
+but you can do
+:: 
+  thread trace dump instructions <#thread index>
+  #e.g.
+  thread trace dump instructions 8
+ 
+to select another thread.
+ 
+Crash Analysis
+--------------
+ 
+What if you are debugging + tracing a process that crashes? 
+Then you can just do
+::
+  thread trace dump instructions
+ 
+To inspect how it crashed! There's nothing special that you need to do. 
+For example
+:: 
+    * thread #1, name = 'a.out', stop reason = signal SIGFPE: integer divide by zero
+        frame #0: 0x00000000004009f1 a.out`main at main.cpp:8:14
+      6       int x;
+      7       cin >> x;
+   -> 8       cout << 12 / x << endl;
+      9       return 0;
+      10  }
+    (lldb) thread trace dump instructions -c 5
+    thread #1: tid = 604302, total instructions = 8388
+      libstdc++.so.6`std::istream::operator>>(int&) + 181
+        [8383] 0x00007ffff7b41665    popq   %rbp
+        [8384] 0x00007ffff7b41666    retq
+      a.out`main + 66 at main.cpp:8:14
+        [8385] 0x00000000004009e8    movl   -0x4(%rbp), %ecx
+        [8386] 0x00000000004009eb    movl   $0xc, %eax
+        [8387] 0x00000000004009f0    cltd
+
+.. note:: 
+  At this moment, we are not including the failed instruction in the trace, 
+  but in the future we might do it for readability.
+ 
+ 
+Offline Trace Analysis
+----------------------
+ 
+It's also possible to record a trace using a custom Intel PT collector 
+and decode + symbolicate the trace using LLDB. 
+For that, the command trace load is useful.
+In order to use trace load, you need to first create a JSON file with 
+the definition of the trace session. 
+For example 
+::
+  {
+    "trace": {
+      "type": "intel-pt",
+      "pt_cpu": {
+        "vendor": "intel",
+        "family": 6,
+        "model": 79,
+        "stepping": 1
+      }
+    },
+    "processes": [
+      {
+        "pid": 815455,
+        "triple": "x86_64-*-linux",
+        "threads": [
+          {
+            "tid": 815455,
+            "traceFile": "trace.file" # raw thread-specific trace from the AUX buffer 
+          }
+        ],
+        "modules": [ # this are all the shared libraries + the main executable
+          {
+            "file": "a.out", # optional if it's the same as systemPath
+            "systemPath": "a.out",
+            "loadAddress": "0x0000000000400000",
+          },
+          {
+            "file": "libfoo.so",
+            "systemPath": "/usr/lib/libfoo.so",
+            "loadAddress": "0x00007ffff7bd9000",
+          },
+          {
+            "systemPath": "libbar.so",
+            "loadAddress": "0x00007ffff79d7000",
+          }
+        ]
+      }
+    ]
+  }
+ 
+You can see the full schema by typing
+::
+  trace schema intel-pt
+ 
+The JSON file mainly contains all the shared libraries that 
+were part of the traced process, along with their memory load address. 
+If the analysis is done on the same computer where the traces were obtained, 
+it's enough to use the “systemPath” field. 
+If the analysis is done on a different machines, these files need to be 
+copied over and the “file” field should point to the 
+location of the file relative to the JSON file.
+Once you have the JSON file and the module files in place, you can simple run
+::
+  lldb
+  > trace load /path/to/json
+  > thread trace dump instructions <optional thread index>
+ 
+Then it's like in the live session case
+
+References
+----------
+
+Original RFC document [the RFC document](https://docs.google.com/document/d/1cOVTGp1sL_HBXjP9eB7qjVtDNr5xnuZvUUtv43G5eVI) for this.
+Some details about how Meta is using Intel Processor Trace can be found 
+in this [blog post](https://engineering.fb.com/2021/04/27/developer-tools/reverse-debugging/).