diff --git a/lldb/source/Plugins/Trace/intel-pt/README.md b/lldb/source/Plugins/Trace/intel-pt/README.md new file mode 100644 --- /dev/null +++ b/lldb/source/Plugins/Trace/intel-pt/README.md @@ -0,0 +1,90 @@ +## 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 git@github.com:intel/libipt.git + ``` + +2. Clone [the LLVM Project](https://github.com/llvm/llvm-project) in its entirety from Github or Phabricator. + ```bash + git clone git@github.com: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 `` and `` 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 + ``` + Run make in the LibIPT build directory + ```bash + cd + make + cd .. + ``` + This will generate a few files in the `/lib` and `/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/include" \ + -DLIBIPT_LIBRARY_PATH="/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 + 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 + ``` + 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® 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