[trace][intel pt] Add TSC timestamps

[wallace]

Summary

I've just added the GetTimestampCounter method to Trace.h, which returns an Optional of a timestamp counter. Major CPU architectures support timestamp counters, which fortunately are invariant in modern chips (i.e. they are synchronized between logical CPUs and increase at a constant rate). This helps with having accurate timestamps even when the the thread is jumping around CPUs.

A followup diff would be to add a GetRealTime method, which would ask the trace plugin to convert a TSC to any of ms/ns/us or just to return the real time if available in the actual trace.

Tools could be built upon any of those two APIs, being GetTimestampCounter way more accurate in terms of keeping relative times.

I also implemented the specific bits for Intel PT. Now the "trace start" command accepts two params: --tsc which enables the generation of timestamp counters, and --psb_period, which is the simplest way to tweak how often these timestamps are generated. There are other ways to increase the resolution of timestamps: CYC and MTC packets, but that can be left for a follow up diff to keep this one short.

wallace@devbig418 ~/llvm-sand/build/Release/fbcode-x86_64/toolchain ▶ ./bin/lldb ~/a.out 
(lldb) target create "/home/wallace/a.out"
Current executable set to '/home/wallace/a.out' (x86_64).
(lldb) b main
Breakpoint 1: where = a.out`main + 9 at main.cpp:6:15, address = 0x0000000000400c5f
(lldb) r
Process 1130363 launched: '/home/wallace/a.out' (x86_64)
Process 1130363 stopped
* thread #1, name = 'a.out', stop reason = breakpoint 1.1
    frame #0: 0x0000000000400c5f a.out`main at main.cpp:6:15
   3    using namespace std;
   4   
   5    int main() {
-> 6      vector<int> s;
   7      s.push_back(1);
   8      s.push_back(2);
   9      cout << s.size() << endl;
(lldb) thread trace start --tsc
(lldb) n
Process 1130363 stopped
* thread #1, name = 'a.out', stop reason = step over
    frame #0: 0x0000000000400c6b a.out`main at main.cpp:7:15
   4   
   5    int main() {
   6      vector<int> s;
-> 7      s.push_back(1);
   8      s.push_back(2);
   9      cout << s.size() << endl;
   10     int x = 1;
(lldb) thread trace dump instructions --tsc -f
thread #1: tid = 1130363
  a.out`main + 9 at main.cpp:6:15
    [ 0] [tsc=0x005a8eadd08764ba] 0x0000000000400c5f    leaq   -0x30(%rbp), %rax
    [ 1] [tsc=0x005a8eadd09356a8] 0x0000000000400c63    movq   %rax, %rdi
    [ 2] [tsc=0x005a8eadd09356a8] 0x0000000000400c66    callq  0x400d9c                  ; std::vector<int, std::allocator<int> >::vector at stl_vector.h:391:7
  ...

[wallace]

nits

[wallace]

nits

[clayborg]

Man cases of having variables named "tsc" or "m_tsc" when it might be clear to have them named "enable_tsc" and "m_enable_tsc".

lldb/source/Commands/Options.td

1071

You mentioned "--psb_period" in your description, but that isn't here. Just wanted to make sure that is on purpose. And if you do add it it should be --psb-period with - and not a _

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

58

Don't use auto here? More readable

87

Is "buffer" binary or text? If text, then this is fine.

104

Do you want an else clause here to error check "ZeroOne" in case you get something like 12 back?

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

85

rename "tsc" to "enable_tsc"?

lldb/source/Plugins/Trace/intel-pt/TraceIntelPTConstants.h

20

"kDefaultTSCValue"? The name above doesn't really convey what this variable is

21

kDefaultPSBPeriod?

[wallace]

address comments + add tests

[wallace]

lldb/source/Commands/Options.td

1071

that's in the TraceIntelPTOptions.td file :), as it's intel pt specific

[clayborg]

Looks good

lldb/docs/lldb-gdb-remote.txt

 //  is stored in an in-memory circular buffer, which keeps the most recent data.
 //
 //  Additional params in the input schema:
 //   {
 //     "threadBufferSize": <decimal integer>,
 //         Trace buffer size per thread in bytes. It must be a power of 2
 //         greater than or equal to 4096 (2^12) bytes.
 //
+//     "enableTsc": <boolean>,
+//         Whether to enable TSC timestamps or not. This is supported on
+//         all devices that support intel-pt. A TSC timestamp is generated along
+//         with PSB (synchronization) packets, whose frequency can be configured
+//         with the "psbPeriod" parameter.
+//
+//     "psbPeriod"?: <Optional decimal integer>,
+//         This value defines the period in which PSB packets will be generated.
+//         A PSB packet is a synchronization packet that contains a TSC
+//         timestamp and the current absolute instruction pointer.
+//
+//         This parameter can only be used if
+//
+//             /sys/bus/event_source/devices/intel_pt/caps/psb_cyc
+//
+//         is 1. Otherwise, the PSB period will be defined by the processor.
+//
+//         If supported, valid values for this period can be found in
+/
+//             /sys/bus/event_source/devices/intel_pt/caps/psb_periods
+//
+//         which contains a hexadecimal number, whose bits represent valid
+//         values e.g. if bit 2 is set, then value 2 is valid.
+//
+//         The psb_period value is converted to the approximate number of
+//         raw trace bytes between PSB packets as:
+//
+//             2 ^ (value + 11)
+//
+//          e.g. value 3 means 16KiB between PSB packets. Defaults to
+//          0 if supported.
+//
 //     /* process tracing only */
 //     "processBufferSizeLimit": <decimal integer>,
 //         Maximum total buffer size per process in bytes.
 //         This limit applies to the sum of the sizes of all trace buffers for
 //         the current process, excluding the ones started with "thread tracing".
 //
 //         Whenever a thread is attempted to be traced due to "process tracing"
 //         and the limit would be reached, the process is stopped with a

 watchpoint_exceptions_received: one of "before" or "after" to specify if a watchpoint is triggered before or after the pc when it stops
 default_packet_timeout: an unsigned number that specifies the default timeout in seconds
 distribution_id: optional. For linux, specifies distribution id (e.g. ubuntu, fedora, etc.)
 osmajor: optional, specifies the major version number of the OS (e.g. for macOS 10.12.2, it would be 10)
 osminor: optional, specifies the minor version number of the OS (e.g. for macOS 10.12.2, it would be 12)
 ospatch: optional, specifies the patch level number of the OS (e.g. for macOS 10.12.2, it would be 2)
 vm-page-size: optional, specifies the target system VM page size, base 10.
            Needed for the "dirty-pages:" list in the qMemoryRegionInfo
-           packet, where a list of dirty pages is sent from the remote 
+           packet, where a list of dirty pages is sent from the remote
            stub.  This page size tells lldb how large each dirty page is.
 addressing_bits: optional, specifies how many bits in addresses are
      significant for addressing, base 10.  If bits 38..0
      in a 64-bit pointer are significant for addressing,
      then the value is 39.  This is needed on e.g. AArch64
      v8.3 ABIs that use pointer authentication, so lldb
      knows which bits to clear/set to get the actual
      addresses.
tuples to return are:
 
     dirty-pages:[<hexaddr>][,<hexaddr]; // A list of memory pages within this
                  // region that are "dirty" -- they have been modified.
                  // Page addresses are in base16.  The size of a page can
                  // be found from the qHostInfo's page-size key-value.
                  //
                  // If the stub supports identifying dirty pages within a
                  // memory region, this key should always be present for all
-                 // qMemoryRegionInfo replies.  This key with no pages 
-                 // listed ("dirty-pages:;") indicates no dirty pages in 
+                 // qMemoryRegionInfo replies.  This key with no pages
+                 // listed ("dirty-pages:;") indicates no dirty pages in
                  // this memory region.  The *absence* of this key means
                  // that this stub cannot determine dirty pages.
 
 If the address requested is not in a mapped region (e.g. we've jumped through
 a NULL pointer and are at 0x0) currently lldb expects to get back the size
 of the unmapped region -- that is, the distance to the next valid region.
 For instance, with a macOS process which has nothing mapped in the first
 4GB of its address space, if we're asking about address 0x2,

lldb/include/lldb/Target/TraceCursor.h

public:
   virtual llvm::Error GetError() = 0;
 
   /// \return
   ///     The load address of the instruction the cursor is pointing at. If the
   ///     cursor points to an error in the trace, return \b
   ///     LLDB_INVALID_ADDRESS.
   virtual lldb::addr_t GetLoadAddress() = 0;
 
+  /// Get the timestamp counter associated with the current instruction.
+  /// Modern Intel, ARM and AMD processors support this counter. However, a
+  /// trace plugin might decide to use a different time unit instead of an
+  /// actual TSC.
+  ///
+  /// \return
+  ///     The timestamp or \b llvm::None if not available.
+  virtual llvm::Optional<uint64_t> GetTimestampCounter() = 0;
+
   /// \return
   ///     The \a lldb::TraceInstructionControlFlowType categories the
   ///     instruction the cursor is pointing at falls into. If the cursor points
   ///     to an error in the trace, return \b 0.
   virtual lldb::TraceInstructionControlFlowType
   GetInstructionControlFlowType() = 0;
   /// \}
 

lldb/include/lldb/Target/TraceInstructionDumper.h

public:
   /// \param[in] initial_index
   ///     Presentation index to use for referring to the current instruction
   ///     of the cursor. If the direction is forwards, the index will increase,
   ///     and if the direction is backwards, the index will decrease.
   ///
   /// \param[in] raw
   ///     Dump only instruction addresses without disassembly nor symbol
   ///     information.
+  ///
+  /// \param[in] show_tsc
+  ///     For each instruction, print the corresponding timestamp counter if
+  ///     available.
   TraceInstructionDumper(lldb::TraceCursorUP &&cursor_up, int initial_index = 0,
-                         bool raw = false);
+                         bool raw = false, bool show_tsc = false);
 
   /// Dump \a count instructions of the thread trace starting at the current
   /// cursor position.
   ///
   /// This effectively moves the cursor to the next unvisited position, so that
   /// a subsequent call to this method continues where it left off.
   ///
   /// \param[in] s
private:
   ///
   /// \return
   ///     \b true if the cursor moved.
   bool TryMoveOneStep();
 
   lldb::TraceCursorUP m_cursor_up;
   int m_index;
   bool m_raw;
+  bool m_show_tsc;
   /// If \b true, all the instructions have been traversed.
   bool m_no_more_data = false;
 };
 
 } // namespace lldb_private
 
 #endif // LLDB_TARGET_TRACE_INSTRUCTION_DUMPER_H

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

 /// See docs/lldb-gdb-remote.txt for more information.
 namespace lldb_private {
 
 /// jLLDBTraceStart gdb-remote packet
 /// \{
 struct TraceIntelPTStartRequest : TraceStartRequest {
   /// Size in bytes to use for each thread's trace buffer.
   int64_t threadBufferSize;
+
+  /// Whether to enable TSC
+  bool enableTsc;
+
+  /// PSB packet period
+  llvm::Optional<int64_t> psbPeriod;
+
   /// Required when doing "process tracing".
   ///
   /// Limit in bytes on all the thread traces started by this "process trace"
   /// instance. When a thread is about to be traced and the limit would be hit,
   /// then a "tracing" stop event is triggered.
   llvm::Optional<int64_t> processBufferSizeLimit;
 };
 

lldb/packages/Python/lldbsuite/test/tools/intelpt/intelpt_testcase.py

def getTraceOrCreate(self):
         return self.target().GetTrace()
 
     def assertSBError(self, sberror, error=False):
         if error:
             self.assertTrue(sberror.Fail())
         else:
             self.assertSuccess(sberror)
 
-    def createConfiguration(self, threadBufferSize=None, processBufferSizeLimit=None):
+    def createConfiguration(self, threadBufferSize=None,
+                            processBufferSizeLimit=None, enableTsc=False,
+                            psbPeriod=None):
         obj = {}
         if processBufferSizeLimit is not None:
             obj["processBufferSizeLimit"] = processBufferSizeLimit
         if threadBufferSize is not None:
-            obj["threadBufferSize"]  = threadBufferSize
+            obj["threadBufferSize"] = threadBufferSize
+        if psbPeriod is not None:
+            obj["psbPeriod"] = psbPeriod
+        obj["enableTsc"] = enableTsc
 
         configuration = lldb.SBStructuredData()
         configuration.SetFromJSON(json.dumps(obj))
         return configuration
 
-    def traceStartThread(self, thread=None, error=False, substrs=None, threadBufferSize=None):
+    def traceStartThread(self, thread=None, error=False, substrs=None,
+                         threadBufferSize=None, enableTsc=False, psbPeriod=None):
         if self.USE_SB_API:
             trace = self.getTraceOrCreate()
             thread = thread if thread is not None else self.thread()
-            configuration = self.createConfiguration(threadBufferSize=threadBufferSize)
+            configuration = self.createConfiguration(
+                threadBufferSize=threadBufferSize, enableTsc=enableTsc,
+                psbPeriod=psbPeriod)
             self.assertSBError(trace.Start(thread, configuration), error)
         else:
             command = "thread trace start"
             if thread is not None:
                 command += " " + str(thread.GetIndexID())
             if threadBufferSize is not None:
                 command += " -s " + str(threadBufferSize)
+            if enableTsc:
+                command += " --tsc"
+            if psbPeriod is not None:
+                command += " --psb-period " + str(psbPeriod)
             self.expect(command, error=error, substrs=substrs)
 
-    def traceStartProcess(self, processBufferSizeLimit=None, error=False, substrs=None):
+    def traceStartProcess(self, processBufferSizeLimit=None, error=False,
+                          substrs=None, enableTsc=False, psbPeriod=None):
         if self.USE_SB_API:
             trace = self.getTraceOrCreate()
-            configuration = self.createConfiguration(processBufferSizeLimit=processBufferSizeLimit)
+            configuration = self.createConfiguration(
+                processBufferSizeLimit=processBufferSizeLimit, enableTsc=enableTsc,
+                psbPeriod=psbPeriod)
             self.assertSBError(trace.Start(configuration), error=error)
         else:
             command = "process trace start"
             if processBufferSizeLimit != None:
                 command += " -l " + str(processBufferSizeLimit)
+            if enableTsc:
+                command += " --tsc"
+            if psbPeriod is not None:
+                command += " --psb-period " + str(psbPeriod)
             self.expect(command, error=error, substrs=substrs)
 
     def traceStopProcess(self):
         if self.USE_SB_API:
             self.assertSuccess(self.target().GetTrace().Stop())
         else:
             self.expect("process trace stop")
 

lldb/source/Commands/CommandObjectThread.cpp

Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
       case 'r': {
         m_raw = true;
         break;
       }
       case 'f': {
         m_forwards = true;
         break;
       }
+      case 't': {
+        m_show_tsc = true;
+        break;
+      }
       default:
         llvm_unreachable("Unimplemented option");
       }
       return error;
     }
 
     void OptionParsingStarting(ExecutionContext *execution_context) override {
       m_count = kDefaultCount;
       m_skip = 0;
       m_raw = false;
       m_forwards = false;
+      m_show_tsc = false;
     }
 
     llvm::ArrayRef<OptionDefinition> GetDefinitions() override {
       return llvm::makeArrayRef(g_thread_trace_dump_instructions_options);
     }
 
     static const size_t kDefaultCount = 20;
 
     // Instance variables to hold the values for command options.
     size_t m_count;
     size_t m_skip;
     bool m_raw;
     bool m_forwards;
+    bool m_show_tsc;
   };
 
   CommandObjectTraceDumpInstructions(CommandInterpreter &interpreter)
       : CommandObjectIterateOverThreads(
             interpreter, "thread trace dump instructions",
             "Dump the traced instructions for one or more threads. If no "
             "threads are specified, show the current thread.  Use the "
             "thread-index \"all\" to see all threads.",
if (!m_dumpers.count(thread_sp->GetID())) {
         if (m_options.m_forwards)
           return cursor_up->Seek(m_options.m_skip, TraceCursor::SeekType::Set);
         return -cursor_up->Seek(-m_options.m_skip, TraceCursor::SeekType::End);
       };
 
       int initial_index = setUpCursor();
 
       auto dumper = std::make_unique<TraceInstructionDumper>(
-          std::move(cursor_up), initial_index, m_options.m_raw);
+          std::move(cursor_up), initial_index, m_options.m_raw,
+          m_options.m_show_tsc);
 
       // This happens when the seek value was more than the number of available
       // instructions.
       if (std::abs(initial_index) < (int)m_options.m_skip)
         dumper->SetNoMoreData();
 
       m_dumpers[thread_sp->GetID()] = std::move(dumper);
     }

lldb/source/Commands/Options.td

let Command = "thread trace dump instructions" in {
   def thread_trace_dump_instructions_skip: Option<"skip", "s">,
     Group<1>,
     Arg<"Index">,
     Desc<"How many instruction to skip from the end of the trace to start "
     "dumping instructions, or from the beginning if --forwards is provided">;
   def thread_trace_dump_instructions_raw : Option<"raw", "r">,
     Group<1>,
     Desc<"Dump only instruction address without disassembly nor symbol information.">;
+  def thread_trace_dump_instructions_show_tsc : Option<"tsc", "t">,
+    Group<1>,
+    Desc<"For each instruction, print the corresponding timestamp counter if available.">;
 }
 
 let Command = "type summary add" in {
   def type_summary_add_category : Option<"category", "w">, Arg<"Name">,
     Desc<"Add this to the given category instead of the default one.">;
   def type_summary_add_cascade : Option<"cascade", "C">, Arg<"Boolean">,
     Desc<"If true, cascade through typedef chains.">;
   def type_summary_add_no_value : Option<"no-value", "v">,
     Desc<"Don't show the value, just show the summary, for this type.">;

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

class IntelPTThreadTrace {
   /// 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);
+  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()) {}
 
 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);
+  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.

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

 //===-- IntelPTManager.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 <sstream>
 
 #include "llvm/ADT/StringRef.h"
 #include "llvm/Support/Error.h"
 #include "llvm/Support/MathExtras.h"
 
 #include "IntelPTManager.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";
 
-/// Return the Linux perf event type for Intel PT.
-static Expected<uint32_t> GetOSEventType() {
-  auto intel_pt_type_text =
-      llvm::MemoryBuffer::getFileAsStream(kOSEventIntelPTTypeFile);
+const char *kPSBPeriodCapFile =
+    "/sys/bus/event_source/devices/intel_pt/caps/psb_cyc";
+
+const char *kPSBPeriodValidValuesFile =
+    "/sys/bus/event_source/devices/intel_pt/caps/psb_periods";
+
+const char *kTSCBitOffsetFile =
+    "/sys/bus/event_source/devices/intel_pt/format/tsc";
+
+const char *kPSBPeriodBitOffsetFile =
+    "/sys/bus/event_source/devices/intel_pt/format/psb_period";
+
+enum IntelPTConfigFileType {
+  Hex = 0,
+  // 0 or 1
+  ZeroOne,
+  Decimal,
+  // a bit index file always starts with the prefix config: following by an int,
+  // which represents the offset of the perf_event_attr.config value where to
+  // store a given configuration.
+  BitOffset
+};
+
+static Expected<uint32_t> ReadIntelPTConfigFile(const char *file,
+                                                IntelPTConfigFileType type) {
+  ErrorOr<std::unique_ptr<MemoryBuffer>> stream =
+      MemoryBuffer::getFileAsStream(file);
 
-  if (!intel_pt_type_text)
+  if (!stream)
     return createStringError(inconvertibleErrorCode(),
-                             "Can't open the file '%s'",
-                             kOSEventIntelPTTypeFile);
+                             "Can't open the file '%s'", file);
+
+  uint32_t value = 0;
+  StringRef text_buffer = stream.get()->getBuffer();
+
+  if (type == BitOffset) {
+    const char *prefix = "config:";
+    if (!text_buffer.startswith(prefix))
+      return createStringError(inconvertibleErrorCode(),
+                               "The file '%s' contents doesn't start with '%s'",
+                               file, prefix);
+    text_buffer = text_buffer.substr(strlen(prefix));
+  }
+
+  auto getRadix = [&]() {
+    switch (type) {
+    case Hex:
+      return 16;
+    case ZeroOne:
+    case Decimal:
+    case BitOffset:
+      return 10;
+    }
+  };
 
-  uint32_t intel_pt_type = 0;
-  StringRef buffer = intel_pt_type_text.get()->getBuffer();
-  if (buffer.trim().getAsInteger(10, intel_pt_type))
+  auto createError = [&](const char *expected_value_message) {
     return createStringError(
         inconvertibleErrorCode(),
-        "The file '%s' has a invalid value. It should be an unsigned int.",
-        kOSEventIntelPTTypeFile);
-  return intel_pt_type;
+        "The file '%s' has an invalid value. It should be %s.", file,
+        expected_value_message);
+  };
+
+  if (text_buffer.trim().consumeInteger(getRadix(), value) ||
+      (type == ZeroOne && value != 0 && value != 1)) {
+    switch (type) {
+    case Hex:
+      return createError("an unsigned hexadecimal int");
+    case ZeroOne:
+      return createError("0 or 1");
+    case Decimal:
+    case BitOffset:
+      return createError("an unsigned decimal int");
+    }
+  }
+  return value;
+}
+/// Return the Linux perf event type for Intel PT.
+static Expected<uint32_t> GetOSEventType() {
+  return ReadIntelPTConfigFile(kOSEventIntelPTTypeFile,
+                               IntelPTConfigFileType::Decimal);
+}
+
+static Error CheckPsbPeriod(size_t psb_period) {
+  Expected<uint32_t> cap =
+      ReadIntelPTConfigFile(kPSBPeriodCapFile, IntelPTConfigFileType::ZeroOne);
+  if (!cap)
+    return cap.takeError();
+  if (*cap == 0)
+    return createStringError(inconvertibleErrorCode(),
+                             "psb_period is unsupported in the system.");
+
+  Expected<uint32_t> valid_values = ReadIntelPTConfigFile(
+      kPSBPeriodValidValuesFile, IntelPTConfigFileType::Hex);
+  if (!valid_values)
+    return valid_values.takeError();
+
+  if (valid_values.get() & (1 << psb_period))
+    return Error::success();
+
+  std::ostringstream error;
+  // 0 is always a valid value
+  error << "Invalid psb_period. Valid values are: 0";
+  uint32_t mask = valid_values.get();
+  while (mask) {
+    int index = __builtin_ctz(mask);
+    if (index > 0)
+      error << ", " << index;
+    // clear the lowest bit
+    mask &= mask - 1;
+  }
+  error << ".";
+  return createStringError(inconvertibleErrorCode(), error.str().c_str());
 }
 
 size_t IntelPTThreadTrace::GetTraceBufferSize() const {
   return m_mmap_meta->aux_size;
 }
 
+static Expected<uint64_t>
+GeneratePerfEventConfigValue(bool enable_tsc, Optional<size_t> psb_period) {
+  uint64_t config = 0;
+  // tsc is always supported
+  if (enable_tsc) {
+    if (Expected<uint32_t> offset = ReadIntelPTConfigFile(
+            kTSCBitOffsetFile, IntelPTConfigFileType::BitOffset))
+      config |= 1 << *offset;
+    else
+      return offset.takeError();
+  }
+  if (psb_period) {
+    if (Error error = CheckPsbPeriod(*psb_period))
+      return std::move(error);
+
+    if (Expected<uint32_t> offset = ReadIntelPTConfigFile(
+            kPSBPeriodBitOffsetFile, IntelPTConfigFileType::BitOffset))
+      config |= *psb_period << *offset;
+    else
+      return offset.takeError();
+  }
+  return config;
+}
+
 Error IntelPTThreadTrace::StartTrace(lldb::pid_t pid, lldb::tid_t tid,
-                                     uint64_t buffer_size) {
+                                     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(ProcessPOSIXLog::GetLogIfAllCategoriesSet(POSIX_LOG_PTRACE));
 
   m_tid = tid;
   LLDB_LOG(log, "called thread id {0}", tid);
   uint64_t page_size = getpagesize();
#else
   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;
-  attr.config = 0;
-
-  Expected<uint32_t> intel_pt_type = GetOSEventType();
 
-  if (!intel_pt_type)
-    return intel_pt_type.takeError();
+  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();
+  }
 
-  LLDB_LOG(log, "intel pt type {0}", *intel_pt_type);
+  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);
if (!cpu_info) {
     cpu_info = std::vector<uint8_t>(
         reinterpret_cast<const uint8_t *>(buffer.getBufferStart()),
         reinterpret_cast<const uint8_t *>(buffer.getBufferEnd()));
   }
   return *cpu_info;
 }
 
 llvm::Expected<IntelPTThreadTraceUP>
-IntelPTThreadTrace::Create(lldb::pid_t pid, lldb::tid_t tid,
-                           size_t buffer_size) {
+IntelPTThreadTrace::Create(lldb::pid_t pid, lldb::tid_t tid, size_t buffer_size,
+                           bool enable_tsc, Optional<size_t> psb_period) {
   IntelPTThreadTraceUP thread_trace_up(new IntelPTThreadTrace());
 
-  if (llvm::Error err = thread_trace_up->StartTrace(pid, tid, buffer_size))
+  if (llvm::Error err = thread_trace_up->StartTrace(pid, tid, buffer_size,
+                                                    enable_tsc, psb_period))
     return std::move(err);
 
   return std::move(thread_trace_up);
 }
 
 Expected<std::vector<uint8_t>>
 IntelPTThreadTrace::GetIntelPTBuffer(size_t offset, size_t size) const {
   std::vector<uint8_t> data(size, 0);

 }
 
 Error IntelPTThreadTraceCollection::TraceStart(
     lldb::tid_t tid, const TraceIntelPTStartRequest &request) {
   if (TracesThread(tid))
     return createStringError(inconvertibleErrorCode(),
                              "Thread %" PRIu64 " already traced", tid);
 
-  Expected<IntelPTThreadTraceUP> trace_up =
-      IntelPTThreadTrace::Create(m_pid, tid, request.threadBufferSize);
+  Expected<IntelPTThreadTraceUP> trace_up = IntelPTThreadTrace::Create(
+      m_pid, tid, request.threadBufferSize, request.enableTsc,
+      request.psbPeriod.map([](int64_t period) { return (size_t)period; }));
   if (!trace_up)
     return trace_up.takeError();
 
   m_total_buffer_size += (*trace_up)->GetTraceBufferSize();
   m_thread_traces.try_emplace(tid, std::move(*trace_up));
   return Error::success();
 }
 

lldb/source/Plugins/Trace/intel-pt/CommandObjectTraceStartIntelPT.h

public:
     Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
                           ExecutionContext *execution_context) override;
 
     void OptionParsingStarting(ExecutionContext *execution_context) override;
 
     llvm::ArrayRef<OptionDefinition> GetDefinitions() override;
 
     size_t m_thread_buffer_size;
+    bool m_enable_tsc;
+    llvm::Optional<size_t> m_psb_period;
   };
 
   CommandObjectThreadTraceStartIntelPT(TraceIntelPT &trace,
                                        CommandInterpreter &interpreter)
       : CommandObjectMultipleThreads(
             interpreter, "thread trace start",
             "Start tracing one or more threads with intel-pt. "
             "Defaults to the current thread. Thread indices can be "
Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
                           ExecutionContext *execution_context) override;
 
     void OptionParsingStarting(ExecutionContext *execution_context) override;
 
     llvm::ArrayRef<OptionDefinition> GetDefinitions() override;
 
     size_t m_thread_buffer_size;
     size_t m_process_buffer_size_limit;
+    bool m_enable_tsc;
+    llvm::Optional<size_t> m_psb_period;
   };
 
   CommandObjectProcessTraceStartIntelPT(TraceIntelPT &trace,
                                         CommandInterpreter &interpreter)
       : CommandObjectParsed(
             interpreter, "process trace start",
             "Start tracing this process with intel-pt, including future "
             "threads. "

lldb/source/Plugins/Trace/intel-pt/CommandObjectTraceStartIntelPT.cpp

case 's': {
     if (option_arg.empty() || option_arg.getAsInteger(0, thread_buffer_size) ||
         thread_buffer_size < 0)
       error.SetErrorStringWithFormat("invalid integer value for option '%s'",
                                      option_arg.str().c_str());
     else
       m_thread_buffer_size = thread_buffer_size;
     break;
   }
+  case 't': {
+    m_enable_tsc = true;
+    break;
+  }
+  case 'p': {
+    int64_t psb_period;
+    if (option_arg.empty() || option_arg.getAsInteger(0, psb_period) ||
+        psb_period < 0)
+      error.SetErrorStringWithFormat("invalid integer value for option '%s'",
+                                     option_arg.str().c_str());
+    else
+      m_psb_period = psb_period;
+    break;
+  }
   default:
     llvm_unreachable("Unimplemented option");
   }
   return error;
 }
 
 void CommandObjectThreadTraceStartIntelPT::CommandOptions::
     OptionParsingStarting(ExecutionContext *execution_context) {
-  m_thread_buffer_size = kThreadBufferSize;
+  m_thread_buffer_size = kDefaultThreadBufferSize;
+  m_enable_tsc = kDefaultEnableTscValue;
+  m_psb_period = kDefaultPsbPeriod;
 }
 
 llvm::ArrayRef<OptionDefinition>
 CommandObjectThreadTraceStartIntelPT::CommandOptions::GetDefinitions() {
   return llvm::makeArrayRef(g_thread_trace_start_intel_pt_options);
 }
 
 bool CommandObjectThreadTraceStartIntelPT::DoExecuteOnThreads(
     Args &command, CommandReturnObject &result,
     llvm::ArrayRef<lldb::tid_t> tids) {
-  if (Error err = m_trace.Start(tids, m_options.m_thread_buffer_size))
+  if (Error err = m_trace.Start(tids, m_options.m_thread_buffer_size,
+                                m_options.m_enable_tsc, m_options.m_psb_period))
     result.SetError(Status(std::move(err)));
   else
     result.SetStatus(eReturnStatusSuccessFinishResult);
 
   return result.Succeeded();
 }
 
 /// CommandObjectProcessTraceStartIntelPT
if (option_arg.empty() ||
         option_arg.getAsInteger(0, process_buffer_size_limit) ||
         process_buffer_size_limit < 0)
       error.SetErrorStringWithFormat("invalid integer value for option '%s'",
                                      option_arg.str().c_str());
     else
       m_process_buffer_size_limit = process_buffer_size_limit;
     break;
   }
+  case 't': {
+    m_enable_tsc = true;
+    break;
+  }
+  case 'p': {
+    int64_t psb_period;
+    if (option_arg.empty() || option_arg.getAsInteger(0, psb_period) ||
+        psb_period < 0)
+      error.SetErrorStringWithFormat("invalid integer value for option '%s'",
+                                     option_arg.str().c_str());
+    else
+      m_psb_period = psb_period;
+    break;
+  }
   default:
     llvm_unreachable("Unimplemented option");
   }
   return error;
 }
 
 void CommandObjectProcessTraceStartIntelPT::CommandOptions::
     OptionParsingStarting(ExecutionContext *execution_context) {
-  m_thread_buffer_size = kThreadBufferSize;
-  m_process_buffer_size_limit = kProcessBufferSizeLimit;
+  m_thread_buffer_size = kDefaultThreadBufferSize;
+  m_process_buffer_size_limit = kDefaultProcessBufferSizeLimit;
+  m_enable_tsc = kDefaultEnableTscValue;
+  m_psb_period = kDefaultPsbPeriod;
 }
 
 llvm::ArrayRef<OptionDefinition>
 CommandObjectProcessTraceStartIntelPT::CommandOptions::GetDefinitions() {
   return llvm::makeArrayRef(g_process_trace_start_intel_pt_options);
 }
 
 bool CommandObjectProcessTraceStartIntelPT::DoExecute(
     Args &command, CommandReturnObject &result) {
   if (Error err = m_trace.Start(m_options.m_thread_buffer_size,
-                                m_options.m_process_buffer_size_limit))
+                                m_options.m_process_buffer_size_limit,
+                                m_options.m_enable_tsc, m_options.m_psb_period))
     result.SetError(Status(std::move(err)));
   else
     result.SetStatus(eReturnStatusSuccessFinishResult);
 
   return result.Succeeded();
 }

lldb/source/Plugins/Trace/intel-pt/DecodedThread.h

 ///
 /// Gaps in the trace can come in a few flavors:
 ///   - tracing gaps (e.g. tracing was paused and then resumed)
 ///   - tracing errors (e.g. buffer overflow)
 ///   - decoding errors (e.g. some memory region couldn't be decoded)
 /// As mentioned, any gap is represented as an error in this class.
 class IntelPTInstruction {
 public:
+  IntelPTInstruction(const pt_insn &pt_insn, uint64_t timestamp)
+      : m_pt_insn(pt_insn), m_timestamp(timestamp) {}
+
   IntelPTInstruction(const pt_insn &pt_insn) : m_pt_insn(pt_insn) {}
 
   /// Error constructor
   ///
   /// libipt errors should use the underlying \a IntelPTError class.
   IntelPTInstruction(llvm::Error err);
 
   /// Check if this object represents an error (i.e. a gap).
   ///
   /// \return
   ///     Whether this object represents an error.
   bool IsError() const;
 
   /// \return
   ///     The instruction pointer address, or \a LLDB_INVALID_ADDRESS if it is
   ///     an error.
   lldb::addr_t GetLoadAddress() const;
 
   /// \return
   ///     An \a llvm::Error object if this class corresponds to an Error, or an
   ///     \a llvm::Error::success otherwise.
   llvm::Error ToError() const;
 
+  /// Get the timestamp associated with the current instruction. The timestamp
+  /// is similar to what a rdtsc instruction would return.
+  ///
+  /// \return
+  ///     The timestamp or \b llvm::None if not available.
+  llvm::Optional<uint64_t> GetTimestampCounter() const;
+
   /// Get the \a lldb::TraceInstructionControlFlowType categories of the
   /// instruction.
   ///
   /// \param[in] next_load_address
   ///     The address of the next instruction in the trace or \b
   ///     LLDB_INVALID_ADDRESS if not available.
   ///
   /// \return
   ///     The control flow categories, or \b 0 if the instruction is an error.
   lldb::TraceInstructionControlFlowType
   GetControlFlowType(lldb::addr_t next_load_address) const;
 
   IntelPTInstruction(IntelPTInstruction &&other) = default;
 
 private:
   IntelPTInstruction(const IntelPTInstruction &other) = delete;
   const IntelPTInstruction &operator=(const IntelPTInstruction &other) = delete;
 
   pt_insn m_pt_insn;
+  llvm::Optional<uint64_t> m_timestamp;
   std::unique_ptr<llvm::ErrorInfoBase> m_error;
 };
 
 /// \class DecodedThread
 /// Class holding the instructions and function call hierarchy obtained from
 /// decoding a trace, as well as a position cursor used when reverse debugging
 /// the trace.
 ///

lldb/source/Plugins/Trace/intel-pt/DecodedThread.cpp

IntelPTInstruction::IntelPTInstruction(llvm::Error err) {
   m_pt_insn.ip = LLDB_INVALID_ADDRESS;
   m_pt_insn.iclass = ptic_error;
 }
 
 bool IntelPTInstruction::IsError() const { return (bool)m_error; }
 
 lldb::addr_t IntelPTInstruction::GetLoadAddress() const { return m_pt_insn.ip; }
 
+Optional<uint64_t> IntelPTInstruction::GetTimestampCounter() const {
+  return m_timestamp;
+}
+
 Error IntelPTInstruction::ToError() const {
   if (!IsError())
     return Error::success();
 
   if (m_error->isA<IntelPTError>())
     return make_error<IntelPTError>(static_cast<IntelPTError &>(*m_error));
   return make_error<StringError>(m_error->message(),
                                  m_error->convertToErrorCode());

lldb/source/Plugins/Trace/intel-pt/IntelPTDecoder.cpp

 //===-- IntelPTDecoder.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 "IntelPTDecoder.h"
 
 #include "llvm/Support/MemoryBuffer.h"
 
+#include "DecodedThread.h"
 #include "TraceIntelPT.h"
 #include "lldb/Core/Module.h"
 #include "lldb/Core/Section.h"
 #include "lldb/Target/Target.h"
 #include "lldb/Target/ThreadPostMortemTrace.h"
 #include "lldb/Utility/StringExtractor.h"
 
 using namespace lldb;
while (true) {
       if (errcode == -pte_eos)
         break;
 
       if (errcode < 0) {
         instructions.emplace_back(make_error<IntelPTError>(errcode, insn.ip));
         break;
       }
 
+      uint64_t time;
+      int time_error = pt_insn_time(&decoder, &time, nullptr, nullptr);
+      if (time_error == -pte_invalid) {
+        // This happens if we invoke the pt_insn_time method incorrectly,
+        // but the instruction is good though.
+        instructions.emplace_back(
+            make_error<IntelPTError>(time_error, insn.ip));
         instructions.emplace_back(insn);
+        break;
+      }
+      if (time_error == -pte_no_time) {
+        // We simply don't have time information, i.e. None of TSC, MTC or CYC
+        // was enabled.
+        instructions.emplace_back(insn);
+      } else {
+        instructions.emplace_back(insn, time);
+      }
     }
   }
 
   return instructions;
 }
 
 /// Callback used by libipt for reading the process memory.
 ///

lldb/source/Plugins/Trace/intel-pt/TraceCursorIntelPT.h

public:
   size_t Seek(int64_t offset, SeekType origin) override;
 
   virtual bool Next() override;
 
   llvm::Error GetError() override;
 
   lldb::addr_t GetLoadAddress() override;
 
+  llvm::Optional<uint64_t> GetTimestampCounter() override;
+
   lldb::TraceInstructionControlFlowType
   GetInstructionControlFlowType() override;
 
   bool IsError() override;
 
 private:
   size_t GetInternalInstructionSize();
 

lldb/source/Plugins/Trace/intel-pt/TraceCursorIntelPT.cpp

 Error TraceCursorIntelPT::GetError() {
   return m_decoded_thread_sp->GetInstructions()[m_pos].ToError();
 }
 
 lldb::addr_t TraceCursorIntelPT::GetLoadAddress() {
   return m_decoded_thread_sp->GetInstructions()[m_pos].GetLoadAddress();
 }
 
+Optional<uint64_t> TraceCursorIntelPT::GetTimestampCounter() {
+  return m_decoded_thread_sp->GetInstructions()[m_pos].GetTimestampCounter();
+}
+
 TraceInstructionControlFlowType
 TraceCursorIntelPT::GetInstructionControlFlowType() {
   lldb::addr_t next_load_address =
       m_pos + 1 < GetInternalInstructionSize()
           ? m_decoded_thread_sp->GetInstructions()[m_pos + 1].GetLoadAddress()
           : LLDB_INVALID_ADDRESS;
   return m_decoded_thread_sp->GetInstructions()[m_pos].GetControlFlowType(
       next_load_address);
 }

lldb/source/Plugins/Trace/intel-pt/TraceIntelPT.h

public:
   const char *GetStartConfigurationHelp() override;
 
   /// Start tracing a live process.
   ///
   /// \param[in] thread_buffer_size
   ///     Trace size per thread in bytes.
   ///
   /// \param[in] total_buffer_size_limit
-  ///     Maximum total trace size per process in bytes. This limit applies to
-  ///     the sum of the sizes of all thread traces of this process, excluding
-  ///     the threads traced explicitly.
-  ///
-  ///     Whenever a thread is attempted to be traced due to this operation and
-  ///     the limit would be reached, the process is stopped with a "tracing"
-  ///     reason, so that the user can retrace the process if needed.
+  ///     Maximum total trace size per process in bytes.
+  ///     More information in TraceIntelPT::GetStartConfigurationHelp().
+  ///
+  /// \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 the operation was successful, or
   ///     \a llvm::Error otherwise.
-  llvm::Error Start(size_t thread_buffer_size, size_t total_buffer_size_limit);
+  llvm::Error Start(size_t thread_buffer_size, size_t total_buffer_size_limit,
+                    bool enable_tsc, llvm::Optional<size_t> psb_period);
 
   /// \copydoc Trace::Start
   llvm::Error Start(StructuredData::ObjectSP configuration =
                         StructuredData::ObjectSP()) override;
 
   /// Start tracing live threads.
   ///
   /// \param[in] tids
   ///     Threads to trace.
   ///
   /// \param[in] thread_buffer_size
   ///     Trace size per thread 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 the operation was successful, or
   ///     \a llvm::Error otherwise.
-  llvm::Error Start(llvm::ArrayRef<lldb::tid_t> tids,
-                    size_t thread_buffer_size);
+  llvm::Error Start(llvm::ArrayRef<lldb::tid_t> tids, size_t thread_buffer_size,
+                    bool enable_tsc, llvm::Optional<size_t> psb_period);
 
   /// \copydoc Trace::Start
   llvm::Error Start(llvm::ArrayRef<lldb::tid_t> tids,
                     StructuredData::ObjectSP configuration =
                         StructuredData::ObjectSP()) override;
 
   /// Get the thread buffer content for a live thread
   llvm::Expected<std::vector<uint8_t>> GetLiveThreadBuffer(lldb::tid_t tid);

lldb/source/Plugins/Trace/intel-pt/TraceIntelPT.cpp

void TraceIntelPT::DoRefreshLiveProcessState(
   }
 }
 
 bool TraceIntelPT::IsTraced(const Thread &thread) {
   RefreshLiveProcessState();
   return m_thread_decoders.count(&thread);
 }
 
+// The information here should match the description of the intel-pt section
+// of the jLLDBTraceStart packet in the lldb/docs/lldb-gdb-remote.txt
+// documentation file. Similarly, it should match the CLI help messages of the
+// TraceIntelPTOptions.td file.
 const char *TraceIntelPT::GetStartConfigurationHelp() {
   return R"(Parameters:
 
   Note: If a parameter is not specified, a default value will be used.
 
   - int threadBufferSize (defaults to 4096 bytes):
     [process and thread tracing]
     Trace size in bytes per thread. It must be a power of 2 greater
     than or equal to 4096 (2^12). The trace is circular keeping the
     the most recent data.
 
+  - boolean enableTsc (default to false):
+    [process and thread tracing]
+    Whether to use enable TSC timestamps or not. This is supported on
+    all devices that support intel-pt.
+
+  - psbPeriod (defaults to null):
+    [process and thread tracing]
+    This value defines the period in which PSB packets will be generated.
+    A PSB packet is a synchronization packet that contains a TSC
+    timestamp and the current absolute instruction pointer.
+
+    This parameter can only be used if
+
+        /sys/bus/event_source/devices/intel_pt/caps/psb_cyc
+
+    is 1. Otherwise, the PSB period will be defined by the processor.
+
+    If supported, valid values for this period can be found in
+
+        /sys/bus/event_source/devices/intel_pt/caps/psb_periods
+
+    which contains a hexadecimal number, whose bits represent
+    valid values e.g. if bit 2 is set, then value 2 is valid.
+
+    The psb_period value is converted to the approximate number of
+    raw trace bytes between PSB packets as:
+
+        2 ^ (value + 11)
+
+    e.g. value 3 means 16KiB between PSB packets. Defaults to 0 if
+    supported.
+
   - int processBufferSizeLimit (defaults to 500 MB):
     [process tracing only]
     Maximum total trace size per process in bytes. This limit applies
     to the sum of the sizes of all thread traces of this process,
     excluding the ones created explicitly with "thread tracing".
     Whenever a thread is attempted to be traced due to this command
     and the limit would be reached, the process is stopped with a
     "processor trace" reason, so that the user can retrace the process
     if needed.)";
 }
 
 Error TraceIntelPT::Start(size_t thread_buffer_size,
-                          size_t total_buffer_size_limit) {
+                          size_t total_buffer_size_limit, bool enable_tsc,
+                          Optional<size_t> psb_period) {
   TraceIntelPTStartRequest request;
   request.threadBufferSize = thread_buffer_size;
   request.processBufferSizeLimit = total_buffer_size_limit;
+  request.enableTsc = enable_tsc;
+  request.psbPeriod = psb_period.map([](size_t val) { return (int64_t)val; });
   request.type = GetPluginName().AsCString();
   return Trace::Start(toJSON(request));
 }
 
 Error TraceIntelPT::Start(StructuredData::ObjectSP configuration) {
-  size_t thread_buffer_size = kThreadBufferSize;
-  size_t process_buffer_size_limit = kProcessBufferSizeLimit;
+  size_t thread_buffer_size = kDefaultThreadBufferSize;
+  size_t process_buffer_size_limit = kDefaultProcessBufferSizeLimit;
+  bool enable_tsc = kDefaultEnableTscValue;
+  Optional<size_t> psb_period = kDefaultPsbPeriod;
 
   if (configuration) {
     if (StructuredData::Dictionary *dict = configuration->GetAsDictionary()) {
       dict->GetValueForKeyAsInteger("threadBufferSize", thread_buffer_size);
       dict->GetValueForKeyAsInteger("processBufferSizeLimit",
                                     process_buffer_size_limit);
+      dict->GetValueForKeyAsBoolean("enableTsc", enable_tsc);
+      dict->GetValueForKeyAsInteger("psbPeriod", psb_period);
     } else {
       return createStringError(inconvertibleErrorCode(),
                                "configuration object is not a dictionary");
     }
   }
 
-  return Start(thread_buffer_size, process_buffer_size_limit);
+  return Start(thread_buffer_size, process_buffer_size_limit, enable_tsc,
+               psb_period);
 }
 
 llvm::Error TraceIntelPT::Start(llvm::ArrayRef<lldb::tid_t> tids,
-                                size_t thread_buffer_size) {
+                                size_t thread_buffer_size, bool enable_tsc,
+                                Optional<size_t> psb_period) {
   TraceIntelPTStartRequest request;
   request.threadBufferSize = thread_buffer_size;
+  request.enableTsc = enable_tsc;
+  request.psbPeriod = psb_period.map([](size_t val) { return (int64_t)val; });
   request.type = GetPluginName().AsCString();
   request.tids.emplace();
   for (lldb::tid_t tid : tids)
     request.tids->push_back(tid);
   return Trace::Start(toJSON(request));
 }
 
 Error TraceIntelPT::Start(llvm::ArrayRef<lldb::tid_t> tids,
                           StructuredData::ObjectSP configuration) {
-  size_t thread_buffer_size = kThreadBufferSize;
+  size_t thread_buffer_size = kDefaultThreadBufferSize;
+  bool enable_tsc = kDefaultEnableTscValue;
+  Optional<size_t> psb_period = kDefaultPsbPeriod;
 
   if (configuration) {
     if (StructuredData::Dictionary *dict = configuration->GetAsDictionary()) {
       dict->GetValueForKeyAsInteger("threadBufferSize", thread_buffer_size);
+      dict->GetValueForKeyAsBoolean("enableTsc", enable_tsc);
+      dict->GetValueForKeyAsInteger("psbPeriod", psb_period);
     } else {
       return createStringError(inconvertibleErrorCode(),
                                "configuration object is not a dictionary");
     }
   }
 
-  return Start(tids, thread_buffer_size);
+  return Start(tids, thread_buffer_size, enable_tsc, psb_period);
 }
 
 Expected<std::vector<uint8_t>>
 TraceIntelPT::GetLiveThreadBuffer(lldb::tid_t tid) {
   return Trace::GetLiveThreadBinaryData(tid, "threadTraceBuffer");
 }

lldb/source/Plugins/Trace/intel-pt/TraceIntelPTConstants.h

 //===-- TraceIntelPTConstants.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_SOURCE_PLUGINS_TRACE_INTEL_PT_CONSTANTS_H
 #define LLDB_SOURCE_PLUGINS_TRACE_INTEL_PT_CONSTANTS_H
 
 #include <cstddef>
 
+#include <llvm/ADT/Optional.h>
+
 namespace lldb_private {
 namespace trace_intel_pt {
 
-const size_t kThreadBufferSize = 4 * 1024;              // 4KB
-const size_t kProcessBufferSizeLimit = 5 * 1024 * 1024; // 500MB
+const size_t kDefaultThreadBufferSize = 4 * 1024;              // 4KB
+const size_t kDefaultProcessBufferSizeLimit = 5 * 1024 * 1024; // 500MB
+const bool kDefaultEnableTscValue = false;
+const llvm::Optional<size_t> kDefaultPsbPeriod = llvm::None;
 
 } // namespace trace_intel_pt
 } // namespace lldb_private
 
 #endif // LLDB_SOURCE_PLUGINS_TRACE_INTEL_PT_CONSTANTS_H

lldb/source/Plugins/Trace/intel-pt/TraceIntelPTOptions.td

 include "../../../../source/Commands/OptionsBase.td"
 
+// The information of the start commands here should match the description of
+// the intel-pt section of the jLLDBTraceStart packet in the
+// lldb/docs/lldb-gdb-remote.txt documentation file. Similarly, it should match
+// the API help message of TraceIntelPT::GetStartConfigurationHelp().
+
 let Command = "thread trace start intel pt" in {
   def thread_trace_start_intel_pt_size: Option<"size", "s">,
     Group<1>,
     Arg<"Value">,
     Desc<"Trace size in bytes per thread. It must be a power of 2 greater "
          "than or equal to 4096 (2^12). The trace is circular keeping "
          "the most recent data. Defaults to 4096 bytes.">;
+  def thread_trace_start_intel_pt_tsc: Option<"tsc", "t">,
+    Group<1>,
+    Desc<"Enable the use of TSC timestamps. This is supported on all devices "
+         "that support intel-pt.">;
+  def thread_trace_start_intel_pt_psb_period: Option<"psb-period", "p">,
+    Group<1>,
+    Arg<"Value">,
+    Desc<"This value defines the period in which PSB packets will be "
+         "generated. A PSB packet is a synchronization packet that contains a "
+         "TSC timestamp and the current absolute instruction pointer. "
+         "This parameter can only be used if "
+         "/sys/bus/event_source/devices/intel_pt/caps/psb_cyc is 1. Otherwise, "
+         "the PSB period will be defined by the processor. If supported, valid "
+         "values for this period can be found in "
+         "/sys/bus/event_source/devices/intel_pt/caps/psb_periods which "
+         "contains a hexadecimal number, whose bits represent valid values "
+         "e.g. if bit 2 is set, then value 2 is valid. The psb_period value is "
+         "converted to the approximate number of raw trace bytes between PSB "
+         "packets as: 2 ^ (value + 11), e.g. value 3 means 16KiB between PSB "
+         "packets. Defaults to 0 if supported.">;
 }
 
 let Command = "process trace start intel pt" in {
   def process_trace_start_intel_pt_thread_size: Option<"thread-size", "s">,
     Group<1>,
     Arg<"Value">,
     Desc<"Trace size in bytes per thread. It must be a power of 2 greater "
          "than or equal to 4096 (2^12). The trace is circular keeping "
          "the most recent data. Defaults to 4096 bytes.">;
   def process_trace_start_intel_pt_process_size_limit: Option<"total-size-limit", "l">,
     Group<1>,
     Arg<"Value">,
     Desc<"Maximum total trace size per process in bytes. This limit applies to "
          "the sum of the sizes of all thread traces of this process, excluding "
          "the ones created with the \"thread trace start\" command. "
          "Whenever a thread is attempted to be traced due to this command and "
          "the limit would be reached, the process is stopped with a "
          "\"processor trace\" reason, so that the user can retrace the process "
          "if needed. Defaults to 500MB.">;
+  def process_trace_start_intel_pt_tsc: Option<"tsc", "t">,
+    Group<1>,
+    Desc<"Enable the use of TSC timestamps. This is supported on all devices "
+         "that support intel-pt.">;
+  def process_trace_start_intel_pt_psb_period: Option<"psb-period", "p">,
+    Group<1>,
+    Arg<"Value">,
+    Desc<"This value defines the period in which PSB packets will be "
+         "generated. A PSB packet is a synchronization packet that contains a "
+         "TSC timestamp and the current absolute instruction pointer. "
+         "This parameter can only be used if "
+         "/sys/bus/event_source/devices/intel_pt/caps/psb_cyc is 1. Otherwise, "
+         "the PSB period will be defined by the processor. If supported, valid "
+         "values for this period can be found in "
+         "/sys/bus/event_source/devices/intel_pt/caps/psb_periods which "
+         "contains a hexadecimal number, whose bits represent valid values "
+         "e.g. if bit 2 is set, then value 2 is valid. The psb_period value is "
+         "converted to the approximate number of raw trace bytes between PSB "
+         "packets as: 2 ^ (value + 11), e.g. value 3 means 16KiB between PSB "
+         "packets. Defaults to 0 if supported.">;
 }

lldb/source/Target/TraceInstructionDumper.cpp

 #include "lldb/Target/Process.h"
 #include "lldb/Target/SectionLoadList.h"
 
 using namespace lldb;
 using namespace lldb_private;
 using namespace llvm;
 
 TraceInstructionDumper::TraceInstructionDumper(lldb::TraceCursorUP &&cursor_up,
-                                               int initial_index, bool raw)
-    : m_cursor_up(std::move(cursor_up)), m_index(initial_index), m_raw(raw) {}
+                                               int initial_index, bool raw,
+                                               bool show_tsc)
+    : m_cursor_up(std::move(cursor_up)), m_index(initial_index), m_raw(raw),
+      m_show_tsc(show_tsc) {}
 
 /// \return
 ///     Return \b true if the cursor could move one step.
 bool TraceInstructionDumper::TryMoveOneStep() {
   if (!m_cursor_up->Next()) {
     SetNoMoreData();
     return false;
   }
void TraceInstructionDumper::DumpInstructions(Stream &s, size_t count) {
   bool was_prev_instruction_an_error = false;
 
   auto printMissingInstructionsMessage = [&]() {
     s.Printf("    ...missing instructions\n");
   };
 
   auto printInstructionIndex = [&]() {
     s.Printf("    [%*d] ", digits_count, m_index);
+
+    if (m_show_tsc) {
+      s.Printf("[tsc=");
+
+      if (Optional<uint64_t> timestamp = m_cursor_up->GetTimestampCounter())
+        s.Printf("0x%016" PRIx64, *timestamp);
+      else
+        s.Printf("unavailable");
+
+      s.Printf("] ");
+    }
   };
 
   InstructionSymbolInfo prev_insn_info;
 
   Target &target = thread_sp->GetProcess()->GetTarget();
   ExecutionContext exe_ctx;
   target.CalculateExecutionContext(exe_ctx);
   const ArchSpec &arch = target.GetArchitecture();

lldb/source/Utility/TraceIntelPTGDBRemotePackets.cpp

 using namespace llvm::json;
 
 namespace lldb_private {
 
 bool fromJSON(const json::Value &value, TraceIntelPTStartRequest &packet,
               Path path) {
   ObjectMapper o(value, path);
   if (!o || !fromJSON(value, (TraceStartRequest &)packet, path) ||
+      !o.map("enableTsc", packet.enableTsc) ||
+      !o.map("psbPeriod", packet.psbPeriod) ||
       !o.map("threadBufferSize", packet.threadBufferSize) ||
       !o.map("processBufferSizeLimit", packet.processBufferSizeLimit))
     return false;
   if (packet.tids && packet.processBufferSizeLimit) {
     path.report("processBufferSizeLimit must be provided");
     return false;
   }
   if (!packet.tids && !packet.processBufferSizeLimit) {
     path.report("processBufferSizeLimit must not be provided");
     return false;
   }
   return true;
 }
 
 json::Value toJSON(const TraceIntelPTStartRequest &packet) {
   json::Value base = toJSON((const TraceStartRequest &)packet);
   base.getAsObject()->try_emplace("threadBufferSize", packet.threadBufferSize);
   base.getAsObject()->try_emplace("processBufferSizeLimit",
                                   packet.processBufferSizeLimit);
+  base.getAsObject()->try_emplace("psbPeriod", packet.psbPeriod);
+  base.getAsObject()->try_emplace("enableTsc", packet.enableTsc);
   return base;
 }
 
 } // namespace lldb_private

lldb/test/API/commands/trace/TestTraceTimestampCounters.py

+import lldb
+from intelpt_testcase import *
+from lldbsuite.test.lldbtest import *
+from lldbsuite.test import lldbutil
+from lldbsuite.test.decorators import *
+
+class TestTraceTimestampCounters(TraceIntelPTTestCaseBase):
+
+    mydir = TestBase.compute_mydir(__file__)
+
+    @testSBAPIAndCommands
+    @skipIf(oslist=no_match(['linux']), archs=no_match(['i386', 'x86_64']))
+    def testTscPerThread(self):
+        self.expect("file " + os.path.join(self.getSourceDir(), "intelpt-trace", "a.out"))
+        self.expect("b main")
+        self.expect("r")
+
+        self.traceStartThread(enableTsc=True)
+
+        self.expect("n")
+        self.expect("thread trace dump instructions --tsc -c 1",
+            patterns=["\[0\] \[tsc=0x[0-9a-fA-F]+\] 0x0000000000400511    movl"])
+
+    @testSBAPIAndCommands
+    @skipIf(oslist=no_match(['linux']), archs=no_match(['i386', 'x86_64']))
+    def testTscPerProcess(self):
+        self.expect("file " + os.path.join(self.getSourceDir(), "intelpt-trace", "a.out"))
+        self.expect("b main")
+        self.expect("r")
+
+        self.traceStartProcess(enableTsc=True)
+
+        self.expect("n")
+        self.expect("thread trace dump instructions --tsc -c 1",
+            patterns=["\[0\] \[tsc=0x[0-9a-fA-F]+\] 0x0000000000400511    movl"])
+
+    @testSBAPIAndCommands
+    @skipIf(oslist=no_match(['linux']), archs=no_match(['i386', 'x86_64']))
+    def testDumpingAfterTracingWithoutTsc(self):
+        self.expect("file " + os.path.join(self.getSourceDir(), "intelpt-trace", "a.out"))
+        self.expect("b main")
+        self.expect("r")
+
+        self.traceStartThread(enableTsc=False)
+
+        self.expect("n")
+        self.expect("thread trace dump instructions --tsc -c 1",
+            patterns=["\[0\] \[tsc=unavailable\] 0x0000000000400511    movl"])
+
+    @testSBAPIAndCommands
+    @skipIf(oslist=no_match(['linux']), archs=no_match(['i386', 'x86_64']))
+    def testPSBPeriod(self):
+        def isPSBSupported():
+            caps_file = "/sys/bus/event_source/devices/intel_pt/caps/psb_cyc"
+            if not os.path.exists(caps_file):
+                return False
+            with open(caps_file, "r") as f:
+                val = int(f.readline())
+                if val != 1:
+                    return False
+            return True
+
+        def getValidPSBValues():
+            values_file = "/sys/bus/event_source/devices/intel_pt/caps/psb_periods"
+            values = []
+            with open(values_file, "r") as f:
+                mask = int(f.readline(), 16)
+                for i in range(0, 32):
+                    if (1 << i) & mask:
+                        values.append(i)
+            return values
+
+
+        if not isPSBSupported():
+            self.skipTest("PSB period unsupported")
+
+        valid_psb_values = getValidPSBValues()
+        # 0 should always be valid, and it's assumed by lldb-server
+        self.assertEqual(valid_psb_values[0], 0)
+
+        self.expect("file " + (os.path.join(self.getSourceDir(), "intelpt-trace", "a.out")))
+        self.expect("b main")
+        self.expect("r")
+
+        # it's enough to test with two valid values
+        for psb_period in (valid_psb_values[0], valid_psb_values[-1]):
+            # we first test at thread level
+            self.traceStartThread(psbPeriod=psb_period)
+            self.traceStopThread()
+
+            # we now test at process level
+            self.traceStartProcess(psbPeriod=psb_period)
+            self.traceStopProcess()
+
+        # we now test invalid values
+        self.traceStartThread(psbPeriod=valid_psb_values[-1] + 1, error=True,
+            substrs=["Invalid psb_period. Valid values are: 0"])
+
+        # TODO: dump the perf_event_attr.config as part of the upcoming "trace dump info"
+        # command and check that the psb period is included there.