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

Tracing with Intel Processor Trace (Intel PT)

2

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

Prerequisites

5

11

15

15–40

Let's keep it concise and direct

20–23

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

25–27

only keep libipt-build

42–60

62–81

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

90

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/source/Plugins/Trace/intel-pt/README.md

+## Instructions to build LLDB with Intel® PT Support
+
+### Before you get started
+
+1. Confirm that your processor is an Intel® x86_64 based processor.
+
+2. Check for the existance of this particular file on your Linux system
+    ```bash
+    cat /sys/bus/event_source/devices/intel_pt/type
+    ```
+    The output of this should be a number greater than ...?
+
+### Build Instructions
+
+1. Clone [LibIPT library](https://github.com/intel/libipt). The Intel® Processor Trace Decoder Library is Intel's® reference implementation for decoding Intel® PT. 
+    ```bash
+    git clone [e-mail]:intel/libipt.git
+    ```
+
+2. Clone [the LLVM Project](https://github.com/llvm/llvm-project) in its entirety from Github or Phabricator.
+    ```bash
+    git clone [e-mail]:llvm/llvm-project.git
+    ```
+
+3. Create build directories for both of these projects, outside the repositories.
+    ```bash
+    mkdir lldb-build libipt-build
+    ```
+
+4. Start by building the libipt library first. LibIPT uses CMake and Make so *make* sure you have those. From here we will use `<lldb-build>` and `<libipt-build>` to represent the full paths of these directories. Change this in the following commands to the full path for your system.
+    ```bash
+    cmake -S libipt -B <libipt-build>
+    ```
+    Run make in the LibIPT build directory
+    ```bash
+    cd <libipt-build>
+    make
+    cd ..
+    ```
+    This will generate a few files in the `<libipt-build>/lib` and `<libipt-build>/libipt/include` directories.
+
+5. Now it is time to build LLDB and link the LibIPT build and header files into it. Start by configuring all the build files for LLDB from LLVM.
+    ```bash
+    cmake \                
+      -B lldb-build \
+      -G Ninja \
+            -DLLVM_ENABLE_PROJECTS="clang;libcxx;lldb;libcxxabi" \
+            -DLLDB_BUILD_INTEL_PT=ON \
+            -DLIBIPT_INCLUDE_PATH="<libipt-build>/libipt/include" \
+            -DLIBIPT_LIBRARY_PATH="<libipt-build>/lib" \
+      -S llvm-project/llvm
+    ```
+    If this step goes right, you should see no errors and **no warnings for unused variables.**
+    We have now configured the LLDB build to be built with Ninja. Make sure you have `ninja` installed.
+
+6. Build LLDB. This will take a while.
+    ```bash
+    cd <lldb-build>
+    ninja lldb lldb-server
+    ```
+
+7. When the build completes after a few decades, test it by running the version you just built.
+    ```bash
+    ./bin/lldb <program>
+    ```
+    Inside LLDB, set a breakpoint and start the process runnning
+    ```lldb
+    (lldb) break main
+    (lldb) run
+    ```
+    Now, if everything went well, when you run the following command, you should see no errors.
+    ```lldb
+    (lldb) process trace start
+    ```
+    You should also be able to see the instructions for any line.
+    ```lldb
+    (lldb) next
+    (lldb) thread trace dump instructions
+    ```
+
+Congratulations, you can now trace away!
+
+### References
+
+Some details about how Intel&reg; Processor Trace works are in [this great blog post](https://engineering.fb.com/2021/04/27/developer-tools/reverse-debugging/).
+Other things about how LLDB works with this are included in [the RFC document](https://docs.google.com/document/d/1cOVTGp1sL_HBXjP9eB7qjVtDNr5xnuZvUUtv43G5eVI/edit#) for this.
+
+- https://easyperf.net/blog/2019/08/23/Intel-Processor-Trace
+- https://easyperf.net/blog/2019/08/30/Intel-PT-part2#appendix-how-to-build-gdb-with-intel-pt-support
+- https://reviews.llvm.org/D91679
 No newline at end of file