[trace][intelpt] Add thin wrapper for perf_event_open API

[jj10306]

Summary

• Add PerfEvent class to handle creating ring buffers and handle the resources associated with the perf_event. This API can be used by the IntelPT collection code and by the future work in this series of diffs related to enabling TSC to timestamp conversion.
• Refactor IntelPT collection code to use this new API
• Add TSC to timestamp conversion logic with unittest

Depends on https://reviews.llvm.org/D121711
Second of the series of smaller diffs that split https://reviews.llvm.org/D120595 up

[jj10306]

Not sure if having this new, separate Perf.h file makes sense as the custom destructors for mmap and file descriptors can be used generally and don't directly relate to the perf API. I added this for the time being based on discussions on https://reviews.llvm.org/D120595, so feedback/thoughts are appreciated.

Also, this is my first time trying to create a "stack" of diffs so I just created the patch with the base being another diff's commit that's currently being reviewed instead of the base being some commit on the mainline - please let me know if there is a better/preferred to do this.

lldb/source/Plugins/Process/Linux/IntelPTCollector.cpp

148

Should this free function be defined here or elsewhere? It's declared in the new Perf.h file

[wallace]

Move FetchPerfTscConversionParameters and StartTrace to the new Perf.h and Perf.cpp files. FetchPerfTscConversionParameters can easily be moved there. StartTrace should be refactored, so that a new method StartPerfEventWithAuxBuffer in Perf.h receives a configuration struct prepared by StartTrace in IntelPTCollector. This new StartPerfEventWithAuxBuffer could return a unique_ptr to a new PerfEvent object with pointers to m_mmap_meta and m_mmap_aux. The destructor of this object could free the resources accordingly. If you are able to do this, you could even share some code between FetchPerfTscConversionParameters and StartPerfEventWithAuxBuffer

[jj10306]

addressed major comment on previous version - see updated title/summary

[wallace]

pretty nice. Most of the comments are stylistic and about the code organization, not the underlying logic, which is overall correct.

lldb/source/Plugins/Process/Linux/IntelPTCollector.cpp

9–25

Btw, there's a code style guideline regarding includes, which can be found here https://llvm.org/docs/CodingStandards.html#include-style. Let's try to follow it from now it. Being honest I wasn't really following it

11–12

do you need these?

229–230

tbh, this method doesn't need to be part of IntelPTThreadTrace. Just leave it as a private static function of this file.
Besides that, we can improve it a bit with the use of errorOrToExpected

246–247

we don't need to change this argument. We might later the behavior of this function to be "allocate the largest buffer possible that is <= the buffer size". Then we don't need to thing of pages anymore from a user point of view.
On the other hand, the PerfEvent API you are building should receive the number of pages as parameter because that's what the documentation says.

251–274

you can move this to a new static method CreateIntelPTPerfEventConfiguration

315

use auto only if the actual type is too complex, which is not the case here, so don't use auto. More here https://llvm.org/docs/CodingStandards.html#use-auto-type-deduction-to-make-code-more-readable

316–317

just use the -> operator instead of creating a new variable

318

that std::move is not needed. It should be done automatically by the compiler

321

i'd asume this std::move is also not needed, but all good if it's here

lldb/source/Plugins/Process/Linux/IntelPTCollector.h

36–62

please move them to be bottom of this class and make them explicitly private

68–71

move the constructor to the top of the class and add documentation. Mention that the perf_event must be the result of a perf_event request for intel pt

76–85

move this method to the top of the class, to make it more readable. Also mention that this is the way to create an instance of this class

127

good one

lldb/source/Plugins/Process/Linux/Perf.cpp

33 ↗

(On Diff #416337)

34 ↗

(On Diff #416337)

the std::move should be able to go away

36 ↗

(On Diff #416337)

remove this, as it should be part of the documentation of GetMetadataPage

46 ↗

(On Diff #416337)

86–95 ↗

(On Diff #416337)

you can move the code that mmaps and checks for errors to a new function

First make resource_handle::MmapUP use always uint8_t instead of allowing a typename. In the end you mmap bytes and the getter methods in PerfEvent can do the casting.

private: 
Expected<resource_handle::MmapUP> PerfEvent::Mmap(size_t size, long int offset, StringRef buffer_name /*for errors*/) {
  errno = 0;
  auto mmap_result = ::mmap(nullptr, size, PROT_READ, MAP_SHARED, GetFd(), offset);

  if (mmap_result == MAP_FAILED) {
    std::string err_msg = llvm::formatv("perf event mmap allocation failed for {0}: {1}",
                                      buffer_name, std::strerror(errno));
    return createStringError(inconvertibleErrorCode(), err_msg);
  }
  return resource_handle::MmapUP(reinterpret_cast<uint8_t *>(mmap_result), size);
}

then you can use it like

Error LoadAuxBuffer(size_t pages) {
  size_t aux_mmap_size = pages * pagesize();
  if (Expected<resource_handle::MmapUP> mmap_aux = Mmap(aux_mmap_size, GetMetadata().aux_offset, "aux buffer"))
    m_aux_buffer = std::move(mmap_aux.get());
  else
    return mmap_aux.takeError();
}

Error LoadMetadataAndDataBuffer(size_t data_pages) {
  size_t size = (data_pages + 1) * pagesize();
  if (Expected<resource_handle::MmapUP> mmap_data = Mmap(size, 0, "metadata and data buffer"))
    m_metadata_and_data_buffer = std::move(mmap_data.get());
  else
    return m_metadata_and_data_buffer.takeError();
}

Error LoadMetadataAndBuffers(size_t data_pages, size_t aux_pages) {
  if (Error err = LoadMetadataAndDataBuffer(data_pages))
    return err;
  if (Error err = LoadAuxBuffer(aux_pages))
    return err;
  return Error::success();
}

perf_event_mmap_page &PerfEvent::GetMetadataPage() const {
 return *reinterpret_cast<perf_event_mmap_page*>(m_metadata_and_data_buffer.get());
}

101–103 ↗

(On Diff #416337)

lldb/source/Plugins/Process/Linux/Perf.h

10

i know not all the code is consistent, but this is the guideline we all should follow
https://llvm.org/docs/CodingStandards.html#header-guard, so you should change this to

LLDB_SOURCE_PLUGINS_PROCESS_LINUX_PERF_H

an example is lldb/source/Plugins/ObjectFile/JIT/ObjectFileJIT.h

13–14

31

rename length to bytes to be more specific

Also add a default value with a length of 0, i.e. MmapDeleter(size_t length = 0). That'll be used for avoiding specifying 0 in the constructor of PerfEvent

31–32

32–34

move the implementation to a cpp file

45

remove this, already done

48

you don't need this

49–55

move the implementation to a cpp file. That will also reduce the number of headers in this file

59–62

Let's remove the template, so that we only deal with bytes. The low-level mmap function works in terms of bytes, so it's better to keep it as it is. This also plays well with the MmapDeleter that deletes a number of bytes.

68–69

94–98

let's keep this short

99–103

As this will be invoked as PerfEvent::InitPerfEvent(, better just rename these methods to Init, so that the user sees PerfEvent::Init(

102–103

Add documentation mentioning the parameters and when to invoke this method over the other

105

move this to the cpp file. Just keep implementation code in a header file if it makes sense to copy it everywhere the header is included, e.g. inline functions

108

111–113

Let's not mention the metadata page here because the fact that the data buffer comes right after the metadata page is an implementation detail.

116

119

we cannot talk about the mmap pointers because that's a minor implementation detail

121

Let's better use a descriptive name: MmapMetadataPageAndBuffers(size_t data_pages, size_t aux_pages)

121–125

blank lines between methods and documentation

123

Return a reference instead of a pointer to enforce the validity of the data, because it can't be nullptr if you are using this method correctly, and it should fail if otherwise

128–134

it's possible that you can do m_mmap_meta() instead of m_mmap_meta(nullptr, resource_handle::MmapDeleter(0)) if MmapDeleter has a parameter-less constructor. All good if you can't

129

rename to m_mmap_metadata_and_data_buffer or have two different mmaps for each chunk of data. If you keep only one, mention in a comment that we can do this because the data buffer comes right after the metadata page

154

can you use the current process' pid with getpid() instead of having the caller pass a pid? That'll make your code simpler

159

remove #ifndef

[jj10306]

lldb/source/Plugins/Process/Linux/IntelPTCollector.cpp

318

it actually is required here

321

it actually is required here

lldb/source/Plugins/Process/Linux/Perf.cpp

34 ↗

(On Diff #416337)

it's actually required here

lldb/source/Plugins/Process/Linux/Perf.h

68–69

I don't think you finished your comment here

111–113

isn't "A value of 0 effectively is a no-op and no data is mmaped for this buffer." a bit misleading since the metadata page will always be mmaped even if 0 is passed?
I agree that it's a no-op for the aux buffer but I think it's worth noting here that the metadata page will always be allocated

[jj10306]

• remove template from MmapUP and use void * instead since this is what mmap returns. Leave casting of the pointer to the getter functions
• refactor internal mmap functions and provide a thin mmap wrapper function that simply forwards parameters to real mmap calls and allows for custom error message. Different callers might need to pass different prot, flag, etc so I decided to include all the mmap parameters, except fd since this is stored on the PerfEvent object itself. This could potentially be changed to accept a fd and be moved out of the PerfEvent class to be used globally since it simply wraps an mmap call and adds custom error messages and resource handling through the unique pointer.
• clean up and add documentation

[wallace]

only some minor documentation change and good to go

lldb/source/Plugins/Process/Linux/IntelPTCollector.h

18

this shouldn't be there.

I'm even more amazed by the fact that

#include "llvm/ADT/DenseMap.h" 
#include "llvm/ADT/DenseSet.h"

are there in the first place. Maybe the intel guy who did this first added them

134

136–140

Too many implementation details. Better not mention them. The reason for avoiding giving too many details is that in the future the implementation might change and this comment won't make sense anymore.

lldb/source/Plugins/Process/Linux/Perf.h

112–117

Let's reduce the number of implementation details that might easily change in the future.

139–140

nice clarification

[jj10306]

Address minor comments and add unittests

[wallace]

some minor final details

lldb/source/Plugins/Process/Linux/Perf.cpp

59–60 ↗

(On Diff #417051)

??

lldb/source/Plugins/Process/Linux/Perf.h

116

254

??

lldb/unittests/Process/Linux/PerfTests.cpp

23 ↗

(On Diff #417051)

39–40 ↗

(On Diff #417051)

use lower_case format. The xray uses a different format

48 ↗

(On Diff #417051)

add a comment before this line explaining how the test will work

54 ↗

(On Diff #417051)

nice!!

also explain here that it's all fine to skip here

70 ↗

(On Diff #417051)

[jj10306]

final cleanup

[wallace]

great job!

lldb/source/Plugins/Process/Linux/IntelPTCollector.h

 //===-- IntelPTCollector.h -------------------------------------- -*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef liblldb_IntelPTCollector_H_
 #define liblldb_IntelPTCollector_H_
 
+#include "Perf.h"
 #include "lldb/Utility/Status.h"
 #include "lldb/Utility/TraceIntelPTGDBRemotePackets.h"
 #include "lldb/lldb-types.h"
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/ADT/DenseSet.h"
 
 #include <linux/perf_event.h>
 #include <sys/mman.h>
 #include <unistd.h>
 
 namespace lldb_private {
 
 namespace process_linux {
 
 /// This class keeps track of one tracing instance of
 /// Intel(R) Processor Trace on Linux OS at thread level.
 ///
 /// The kernel interface for us is the perf_event_open.
 class IntelPTThreadTrace;
 typedef std::unique_ptr<IntelPTThreadTrace> IntelPTThreadTraceUP;
 
 class IntelPTThreadTrace {
 
-  class munmap_delete {
-    size_t m_length;
-
-  public:
-    munmap_delete(size_t length) : m_length(length) {}
-    void operator()(void *ptr) {
-      if (m_length)
-        munmap(ptr, m_length);
-    }
-  };
-
-  class file_close {
-
-  public:
-    file_close() = default;
-    void operator()(int *ptr) {
-      if (ptr == nullptr)
-        return;
-      if (*ptr == -1)
-        return;
-      close(*ptr);
-      std::default_delete<int>()(ptr);
-    }
-  };
-
-  std::unique_ptr<perf_event_mmap_page, munmap_delete> m_mmap_meta;
-  std::unique_ptr<uint8_t, munmap_delete> m_mmap_aux;
-  std::unique_ptr<int, file_close> m_fd;
+  std::unique_ptr<perf_event_mmap_page, resource_handle::munmap_delete>
+      m_mmap_meta;
+  std::unique_ptr<uint8_t, resource_handle::munmap_delete> m_mmap_aux;
+  std::unique_ptr<int, resource_handle::file_close> m_fd;
   lldb::tid_t m_tid;
 
   /// Start tracing a thread
   ///
   /// \param[in] pid
   ///     The pid of the process whose thread will be traced.
   ///
   /// \param[in] buffer_size
   ///     Size of the thread buffer in bytes.
   ///
   /// \param[in] enable_tsc
   ///     Whether to use enable TSC timestamps or not.
   ///     More information in TraceIntelPT::GetStartConfigurationHelp().
   ///
   /// \param[in] psb_period
   ///     This value defines the period in which PSB packets will be generated.
   ///     More information in TraceIntelPT::GetStartConfigurationHelp().
   ///
   /// \return
   ///     \a llvm::Error::success if tracing was successful, or an
   ///     \a llvm::Error otherwise.
   llvm::Error StartTrace(lldb::pid_t pid, lldb::tid_t tid, uint64_t buffer_size,
                          bool enable_tsc, llvm::Optional<size_t> psb_period);
 
   llvm::MutableArrayRef<uint8_t> GetAuxBuffer() const;
   llvm::MutableArrayRef<uint8_t> GetDataBuffer() const;
 
   IntelPTThreadTrace()
-      : m_mmap_meta(nullptr, munmap_delete(0)),
-        m_mmap_aux(nullptr, munmap_delete(0)), m_fd(nullptr, file_close()) {}
+      : m_mmap_meta(nullptr, resource_handle::munmap_delete(0)),
+        m_mmap_aux(nullptr, resource_handle::munmap_delete(0)),
+        m_fd(nullptr, resource_handle::file_close()) {}
 
 public:
   /// Get the content of /proc/cpuinfo that can be later used to decode traces.
   static llvm::Expected<llvm::ArrayRef<uint8_t>> GetCPUInfo();
 
   /// Start tracing a thread.
   ///
   /// See \a StartTrace.
   ///
   /// \return
   ///   A \a IntelPTThreadTrace instance if tracing was successful, or
   ///   an \a llvm::Error otherwise.
   static llvm::Expected<IntelPTThreadTraceUP>
   Create(lldb::pid_t pid, lldb::tid_t tid, size_t buffer_size, bool enable_tsc,
          llvm::Optional<size_t> psb_period);
 
   /// Read the trace buffer of the currently traced thread.
   ///
   /// \param[in] offset
   ///     Offset of the data to read.
   ///
   /// \param[in] size
   ///     Number of bytes to read.
public:
   ///
   /// \param[in] src_cyc_index
   ///     The index pointer (start of the valid data in the cyclic
   ///     buffer).
   ///
   /// \param[in] offset
   ///     The offset to begin reading the data in the cyclic buffer.
   static void ReadCyclicBuffer(llvm::MutableArrayRef<uint8_t> &dst,
                                llvm::MutableArrayRef<uint8_t> src,
                                size_t src_cyc_index, size_t offset);
 
   /// Return the thread-specific part of the jLLDBTraceGetState packet.
   TraceThreadState GetState() const;
 };
 
 /// Manages a list of thread traces.
 class IntelPTThreadTraceCollection {
 public:
   IntelPTThreadTraceCollection(lldb::pid_t pid) : m_pid(pid) {}
 
   /// Dispose of all traces
   void Clear();
 
   bool TracesThread(lldb::tid_t tid) const;
 
   size_t GetTotalBufferSize() const;
 
   std::vector<TraceThreadState> GetThreadStates() const;
 
   llvm::Expected<const IntelPTThreadTrace &>

lldb/source/Plugins/Process/Linux/IntelPTCollector.cpp

 //===-- IntelPTCollector.cpp ------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include <algorithm>
 #include <fstream>
+#include <linux/perf_event.h>
 #include <sstream>
 
 #include "llvm/ADT/StringRef.h"
 #include "llvm/Support/Error.h"
 #include "llvm/Support/MathExtras.h"
 
 #include "IntelPTCollector.h"
+#include "Perf.h"
 #include "Plugins/Process/POSIX/ProcessPOSIXLog.h"
 #include "lldb/Host/linux/Support.h"
 #include "lldb/Utility/StreamString.h"
 
 #include <sys/ioctl.h>
 #include <sys/syscall.h>
 
 using namespace lldb;
 using namespace lldb_private;
 using namespace process_linux;
 using namespace llvm;
 
 const char *kOSEventIntelPTTypeFile =
     "/sys/bus/event_source/devices/intel_pt/type";
while (mask) {
     if (index > 0)
       error << ", " << index;
     // clear the lowest bit
     mask &= mask - 1;
   }
   error << ".";
   return createStringError(inconvertibleErrorCode(), error.str().c_str());
 }
+llvm::Expected<PerfTscConversionParameters>
+FetchPerfTscConversionParameters(lldb::pid_t pid) {
+  perf_event_attr attr;
+  memset(&attr, 0, sizeof(attr));
+  // Set the minimum attributes necessary to access the mmap metadata page.
+  attr.size = sizeof(attr);
+  attr.type = PERF_TYPE_SOFTWARE;
+  attr.config = PERF_COUNT_SW_DUMMY;
+
+  errno = 0;
+  auto fd = syscall(SYS_perf_event_open, &attr, pid, -1, -1, 0);
+  if (fd == -1) {
+    std::string err_msg =
+        llvm::formatv("perf event syscall failed: {0}", std::strerror(errno));
+    return llvm::createStringError(llvm::inconvertibleErrorCode(), err_msg);
+  }
+  auto fd_handle = std::unique_ptr<int, resource_handle::file_close>(
+      new int(fd), resource_handle::file_close());
+
+  uint64_t page_size = getpagesize();
+  errno = 0;
+  auto base = mmap(nullptr, page_size, PROT_READ, MAP_SHARED, fd, 0);
+
+  if (base == MAP_FAILED) {
+    std::string err_msg = llvm::formatv("perf mmap meta allocation failed: {0}",
+                                        std::strerror(errno));
+    return llvm::createStringError(llvm::inconvertibleErrorCode(), err_msg);
+  }
+  auto perf_mmap_meta_handle =
+      std::unique_ptr<perf_event_mmap_page, resource_handle::munmap_delete>(
+          reinterpret_cast<perf_event_mmap_page *>(base),
+          resource_handle::munmap_delete(page_size));
+
+  if (perf_mmap_meta_handle->cap_user_time &&
+      perf_mmap_meta_handle->cap_user_time_zero) {
+    return PerfTscConversionParameters{perf_mmap_meta_handle->time_mult,
+                                       perf_mmap_meta_handle->time_shift,
+                                       perf_mmap_meta_handle->time_zero};
+  } else {
+    auto err_cap = !perf_mmap_meta_handle->cap_user_time ? "cap_user_time"
+                                                         : "cap_user_time_zero";
+    std::string err_msg = llvm::formatv(
+        "{0} not supported. TSC cannot be converted to time unit", err_cap);
+    return llvm::createStringError(llvm::inconvertibleErrorCode(), err_msg);
+  }
+}
 
 size_t IntelPTThreadTrace::GetTraceBufferSize() const {
 #ifndef PERF_ATTR_SIZE_VER5
   llvm_unreachable("Intel PT Linux perf event not supported");
 #else
   return m_mmap_meta->aux_size;
 #endif
 }
if (psb_period) {
     else
       return offset.takeError();
   }
   return config;
 }
 
 Error IntelPTThreadTrace::StartTrace(lldb::pid_t pid, lldb::tid_t tid,
                                      uint64_t buffer_size, bool enable_tsc,
                                      Optional<size_t> psb_period) {
 #ifndef PERF_ATTR_SIZE_VER5
   llvm_unreachable("Intel PT Linux perf event not supported");
 #else
   Log *log = GetLog(POSIXLog::Ptrace);
 
   m_tid = tid;
   LLDB_LOG(log, "called thread id {0}", tid);
   uint64_t page_size = getpagesize();
 
   if (__builtin_popcount(buffer_size) != 1 || buffer_size < 4096) {
     return createStringError(
         inconvertibleErrorCode(),
         "The trace buffer size must be a power of 2 greater than or equal to "
         "4096 (2^12) bytes. It was %" PRIu64 ".",
         buffer_size);
   }
   uint64_t numpages = static_cast<uint64_t>(
       llvm::PowerOf2Floor((buffer_size + page_size - 1) / page_size));
   numpages = std::max<uint64_t>(1, numpages);
   buffer_size = page_size * numpages;
 
   perf_event_attr attr;
   memset(&attr, 0, sizeof(attr));
   attr.size = sizeof(attr);
   attr.exclude_kernel = 1;
   attr.sample_type = PERF_SAMPLE_TIME;
   attr.sample_id_all = 1;
   attr.exclude_hv = 1;
   attr.exclude_idle = 1;
   attr.mmap = 1;
 
   if (Expected<uint64_t> config_value =
           GeneratePerfEventConfigValue(enable_tsc, psb_period)) {
     attr.config = *config_value;
     LLDB_LOG(log, "intel pt config {0}", attr.config);
   } else {
     return config_value.takeError();
   }
 
   if (Expected<uint32_t> intel_pt_type = GetOSEventType()) {
     attr.type = *intel_pt_type;
     LLDB_LOG(log, "intel pt type {0}", attr.type);
   } else {
     return intel_pt_type.takeError();
   }
 
   LLDB_LOG(log, "buffer size {0} ", buffer_size);
 
   errno = 0;
   auto fd =
       syscall(SYS_perf_event_open, &attr, static_cast<::tid_t>(tid), -1, -1, 0);
   if (fd == -1) {
     LLDB_LOG(log, "syscall error {0}", errno);
     return createStringError(inconvertibleErrorCode(),
                              "perf event syscall failed");
   }
 
-  m_fd = std::unique_ptr<int, file_close>(new int(fd), file_close());
+  m_fd = std::unique_ptr<int, resource_handle::file_close>(
+      new int(fd), resource_handle::file_close());
 
   errno = 0;
   auto base =
       mmap(nullptr, (buffer_size + page_size), PROT_WRITE, MAP_SHARED, fd, 0);
 
   if (base == MAP_FAILED) {
     LLDB_LOG(log, "mmap base error {0}", errno);
     return createStringError(inconvertibleErrorCode(),
                              "Meta buffer allocation failed");
   }
 
-  m_mmap_meta = std::unique_ptr<perf_event_mmap_page, munmap_delete>(
+  m_mmap_meta =
+      std::unique_ptr<perf_event_mmap_page, resource_handle::munmap_delete>(
           reinterpret_cast<perf_event_mmap_page *>(base),
-      munmap_delete(buffer_size + page_size));
+          resource_handle::munmap_delete(buffer_size + page_size));
 
   m_mmap_meta->aux_offset = m_mmap_meta->data_offset + m_mmap_meta->data_size;
   m_mmap_meta->aux_size = buffer_size;
 
   errno = 0;
   auto mmap_aux = mmap(nullptr, buffer_size, PROT_READ, MAP_SHARED, fd,
                        static_cast<long int>(m_mmap_meta->aux_offset));
 
   if (mmap_aux == MAP_FAILED) {
     LLDB_LOG(log, "second mmap done {0}", errno);
     return createStringError(inconvertibleErrorCode(),
                              "Trace buffer allocation failed");
   }
-  m_mmap_aux = std::unique_ptr<uint8_t, munmap_delete>(
-      reinterpret_cast<uint8_t *>(mmap_aux), munmap_delete(buffer_size));
+  m_mmap_aux = std::unique_ptr<uint8_t, resource_handle::munmap_delete>(
+      reinterpret_cast<uint8_t *>(mmap_aux),
+      resource_handle::munmap_delete(buffer_size));
   return Error::success();
 #endif
 }
 
 llvm::MutableArrayRef<uint8_t> IntelPTThreadTrace::GetDataBuffer() const {
 #ifndef PERF_ATTR_SIZE_VER5
   llvm_unreachable("Intel PT Linux perf event not supported");
 #else
   return MutableArrayRef<uint8_t>(
       (reinterpret_cast<uint8_t *>(m_mmap_meta.get()) +

lldb/source/Plugins/Process/Linux/Perf.h

+//===-- Perf.h --------------------------------------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef lldb_Perf_H_
+#define lldb_Perf_H_
+
+#include "lldb/lldb-types.h"
+#include "llvm/Support/Error.h"
+
+#include <sys/mman.h>
+#include <unistd.h>
+
+namespace lldb_private {
+namespace process_linux {
+namespace resource_handle {
+
+/// Custom deleter for the pointer returned by \a mmap.
+///
+/// This functor type is provided to \a unique_ptr to properly
+/// unmap the region at destruction time.
+class munmap_delete {
+public:
+  munmap_delete(size_t length) : m_length(length) {}
+  void operator()(void *ptr) {
+    if (m_length)
+      munmap(ptr, m_length);
+  }
+
+private:
+  size_t m_length;
+};
+
+/// Custom deleter for a file descriptor.
+///
+/// This functor type is provided to \a unique_ptr to properly release
+/// the resources associated with the file descriptor at destruction time.
+class file_close {
+public:
+  file_close() = default;
+  void operator()(int *ptr) {
+    if (ptr == nullptr)
+      return;
+    if (*ptr == -1)
+      return;
+    close(*ptr);
+    std::default_delete<int>()(ptr);
+  }
+};
+} // namespace resource_handle
+
+/// TSC to nanoseconds conversion values defined by the Linux perf_event API
+/// when the capibilities cap_user_time and cap_user_time_zero are set. See the
+/// documentation of `time_zero` in
+/// https://man7.org/linux/man-pages/man2/perf_event_open.2.html for more
+/// information.
+struct PerfTscConversionParameters {
+  uint32_t m_time_mult;
+  uint16_t m_time_shift;
+  uint64_t m_time_zero;
+};
+
+/// Fetch \a PerfTscConversionParameters from \a perf_event_mmap_page, if
+/// available.
+///
+/// \param[in] pid
+///     pid used to make the perf_event_open syscall.
+llvm::Expected<PerfTscConversionParameters>
+FetchPerfTscConversionParameters(lldb::pid_t pid);
+
+} // namespace process_linux
+} // namespace lldb_private
+
+#endif // #ifndef lldb_Perf_H_