[WIP][trace][intelpt] Add TSC to Nanosecond conversion for IntelPT traces

[jj10306]

Summary

TSC to timestamp conversion for IntelPT traces and other minor improvements:

• Add TimestampCounterRate abstract class and concrete implementation PerfTimestampCounterRate that gets conversion values from Linux's perf event API - perf_event_mmap_page
• Add resource_handle namespace to allow for reuse of file descriptor and munmap resource handles
• Cache TimestampCounterRateSP on server side in IntelPTCollector and client side in TraceIntelPT
• Update DecodedThread to allow for access to the conversion values from the TraceCursor
• Add GetNanos (to be renamed) API to TraceCursor to allow for conversion of a trace instruction's TSC value to nanoseconds
• Update trace schema and trace save commands to accommodate schema changes
• Rename IntelPTManager to IntelPTCollector

TODO:

• add unittests
• Decide on an descriptive name and other minor comments from @wallace @davidca on previous version of diff
  • Make naming consistent across all changes after the naming is decided upon
• Decide how to utilize the new TraceCursor::toNanos() API in instruction dump output
• Make documentation in lldb-gdb-remote.txt` and GetSchema() clean and descriptive given the potential for different flavors of TimestampCounterRate

[jj10306]

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

51

What is the suggested way to serialize a u64 into JSON? I thought of two approaches:

1. Store two separate u32
2. store the integer as a string

@wallace wdyt?

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

22

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

188

Not sure TraceIntelPT is the correct spot to cache the converter on the client side. It will depend on how this new logic is integrated with the decoders, but curious to get your initial feedback on this.

lldb/source/Utility/TraceIntelPTGDBRemotePackets.cpp

75–76

[wallace]

you got the flow correct. I left comments regarding specific details, but good job overall!!

lldb/docs/lldb-gdb-remote.txt

454–479

don't forget to f

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

51

you don't need to use int64_t here. You can use the real types here and do the conversion in the fromJson and toJson methods

55

TscToWallTimeConverter is a better name

55

use a class and not a struct. A struct has all its member public and we don't want that

58

ToNanos() is also okay. Up to you

63

64–66

you can get rid of the constructors a

70

you don't need this struct. You should just put the 3 fields here.

86

it's weird for a bag of data to contain a field transmitted by json called coverter. Just call it TimestampCounterRate. Because that's what it is. Then each TimestampCounterRate subclass can have a ToNanos(uint64_t tsc) method that converts to that.
Your documentation should specific if this ToNanos method returns the since the start of the computer, or since the start of the program, or anything else

89

Create a typedef in this file called TimestampCounterRateSP for readability. You can use tsc_rate as your variable names

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

45

remove it from here

257–259

notice the case is which g_tsc_rate is not None but nullptr. That means that the computation was performed but no rate was found, so the computation won't happen again. We have to make the code in that way because it's possible that checking for some rates is not a no-op. E.g. you can run a little 10ms program and calculate the difference in TSC to get an estimated rate.

Besides that, put all of this in a new function

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

238

static llvm::Optional<TimestampCounterRateSP> g_tsc_rate; // by default this is None

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

22

memory should be defined as a new include block between lines 9 and 11. That's just the pattern we follow

214

just replace the converter if you got a new one from the state. IT's cheap

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

187

this is null by default, no need to mention it

188

this is the right place to cache it, right next to m_cpu_info

lldb/source/Target/Trace.cpp

191–202

you can combine these blocks

lldb/source/Utility/TraceIntelPTGDBRemotePackets.cpp

56

fail fast whenever you can

59

you don't need to pass PerfTscConverter. make_shared should be smart enough to create the object by itself

59–60

if you do this, then you can fail fast and do the int conversions here, without polluting your class

66–68

delete this

69

return false; if you got here, then you have a kind that is not available

74

o.mapOptional is what you need here. That will return true if "tsc_conversion" is not available or if it's well-formed.

84–86

here you should cast to int64_t

[jj10306]

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

51

What is the suggested way to serialize a u64 into JSON? I thought of two approaches:

1. Store two separate u32
2. store the integer as a string

@wallace wdyt?

64–66

Need the 3 arg constructor to create an instance of this class in IntelPTManager.cpp and need the default constructor for when we create an uninitialized instance of the class before mapping the values from JSON in the fromJSON method.

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

45

Without a definition of the static member outside of the class, a linker error occurs.

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

238

Is the idea of wrapping the SP in an Optional here allows us to represent 3 different states?

1. None: we have not yet attempted to fetch/calculate the tsc rate.
2. nullptr: we tried to fetch the rate but one does not exist
3. <non-null SP>: the rate that was successfully fetched

Without the Optional, we cannot distinguish between the first two cases.

Please let me know if my understanding is correct.

lldb/source/Utility/TraceIntelPTGDBRemotePackets.cpp

69

in this case should we also set the SP value to be nullptr? Otherwise that value will still be None which, from my understanding, indicates that the TscRate has not yet been fetched whereas nullptr indicates that the we have tried to fetch the rate but it does not exist.

74

From looking at the source of map and mapOptional it appears that the only difference is that map sets Out to None whereas mapOptional leaves it unchanged, they both return true in the case that the property doesn't exist.

Given this, it's not immediately obvious to me which we should be using in this case - do we want the tsc_conversion to be set to None or left unchanged in the case that it's not present in the JSON?

84–86

How should we handle serializing m_time_zero since it's uint64_t and the JSON library only supports int64_t for number types?

[jj10306]

Address comments, still need to handle uint64_t JSON serialization correctly. I plan to proceed with decoder and schema changes now that initial feedback has been received and addressed.

[wallace]

in terms of functionality, everything is right, but you need to do some improvements

lldb/docs/lldb-gdb-remote.txt

454–480

you have to improve the documentation and formatting following the existing documentation's format

lldb/include/lldb/Target/Trace.h

306

JSON string representing the jLLDBTraceGetState response. It might be invalid.

310

you don't need to return a unique_ptr for this. There's nothing that you want to forbid copies of. Just return

llvm::Optional<TraceGetStateResponse>

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

14

undo this

43

TSC is not a very well known concept, so better be very explanatory in the documentation

Class that can be extended to represent different CPU Time Stamp Counter (TSC) frequency rates, which can be used to convert TSCs to common units of time, such as nanoseconds. More on TSCs can be found here https://en.wikipedia.org/wiki/Time_Stamp_Counter.

47

[wallace]

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

51

i'll respond below

53

modern c++ uses the using keyword.

using TimestampCounterRateSP = std::shared_ptr<TimestampCounterRate>;

use the version you want

55–56

You have to make the documentation very friendly to newcomers.

59

do you need this?

61

why do you do static_cast<int64_t>?

66–68

having the correct types here is the right thing to do

72

The response contains the frequency rate. Whether it's used to convert to nanos or not is a different topic.

Just delete this line.

74

avoid using nullptr when you have an Optional.

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

45

makes sense

257

sadly you can't put this here. If you do this, then GetState() will only work correctly if StartTrace() was invoked first. What if in the future we have a different flow in which lldb-server uses an additional tracing function besides StartTrace() and that new function forgets to set the tsc_rate?
This is called coupling and should be avoided.

What you should do instead is to create a new static function called llvm::Optional<TimestampCounterRateSP >GetTscRate() that will perform the perf_event request or reuse a previously saved value. It should work regardless of when it's invoked.

652

only set it if not None

if (Optional<...> tsc_rate_sp = IntelPTManager::GetTSCRate())
  state.tsc_rate = tsc_rate_sp;

700

GetTscRate is a better name, because eventually we might want to include other fallback mechanisms

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

211

don't forget to add documentation here

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

195

return None

205

None

214

make sure that everything works when lldb-server doesn't have support for the perf zero cap

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

187

use the same documentation I suggest above for the state object

lldb/source/Target/Trace.cpp

191

you are not storing live_process_state elsewhere. Just use an optional. That's all you need

191

you can fail faster to keep everything cleaner

lldb/source/Utility/TraceIntelPTGDBRemotePackets.cpp

60

int64_t, and give proper names

65

path.report("unsupported TSC rate kind");

make sure to write a test with malformed data

70

just return the bool

80

this kind of casting is all fine. Look at this code

#include <iostream>
#include <climits>
using namespace std;

int main() {
  uint64_t x = ULONG_MAX; // 0xFFFFFFFF;
  cout << x << endl;
  cout << (int64_t)x << endl;
  cout << (uint64_t)(int64_t)x << endl;
}

and the output is

18446744073709551615
-1
18446744073709551615

The same works for ULONG_MAX - 1, which is equivalent to -2.

So that means that there's no conversion loss

86–91

the code is simpler is you make strict use of the shared pointer only for valid cases

[labath]

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

74

Ideally this would be a plain TimestampCounterRateSP variable and nullptr would denote emptyness. Since (shared) pointers already have a natural empty state, it's best to use that. Adding an extra Optional layer just creates ambiguity.

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

22

It's actually a pattern we should not follow. When all of the includes are grouped in one block, then clang-format automatically reorders them to conform to the llvm coding standards.

[davidca]

lldb/docs/lldb-gdb-remote.txt

469

why is all this called tsc rate? there is also offset in this conversion. What about something like tsc_conversion_params or tsc_conv

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

44

nit, Intel documentation and kernel refers this as TSC, not TimestampCounter, in order to differentiate this awful name from everywhere else that "Timestamp" and "Counter" is used. Perhaps embrace TSC to make it easier to google info?

47

To be precise, it's number of nanoseconds since boot. You should also add that this nanoseconds clock is sched_clock https://www.kernel.org/doc/html/latest/timers/timekeeping.html

In fact, you may want to use sched_clock as the name for this clock, rather than Nanos as in the next lines.

78–80

should this two be static factory methods?

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

257

1. this is not a Get* method. This is populating a global. Get* are inexpensive methods that return a value.

2. if the TSC conversion parameters will be stored in a global, why not to use the Singleton pattern?

3. TSC parameters change over time. I really think that should be stored within IntelPTManager. Obtaining this parameters is a ~10 microseconds operation, so it's fine if they need to be read next time an IntelPTManager is created.

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

211

how is ti

[wallace]

Thanks @davidca and @labath for chiming in.
@jj10306, please rename IntelPTManager to IntelPTCollector for clarity.

lldb/docs/lldb-gdb-remote.txt

469

tsc_conversion_params seems like a good idea

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

44

Ahh!! Then let's do what David says. Let's call it tsc everywhere

74

Good idea

78–80

That's just the pattern most json conversion utils follow. It helps with some templating stuff

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

257

Can tsc frequency rates change even in modern cpus?. In this case, it's no brainer we need to calculate this number all the time.

I also agree with point number 1.

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

211

@davidca, i think you didn't finish your comment

[jj10306]

Will update naming and other issues once the couple minor discussions with @wallace and @davidca in the comments are complete.

lldb/docs/lldb-gdb-remote.txt

469

Agreed, making that change!

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

44

Which do you think is a better name to replace TimestampCounterRate with - TscConversionParams (as mentioned in the previous comment, "tsc_conversion_params" will be the new key in the TraceGetState packet schema, so this would be consistent with that) or TscConversioninfo or TscConverter (since the function of the class is to provide functionality to convert Tsc to time)?
@davidca @wallace wdyt?

47

Chapter 17.7 of Intel's software developer manual (volume 3) states the following:
"The time-stamp counter (as implemented in the P6 family, Pentium, Pentium M, Pentium 4, Intel Xeon, Intel Core
Solo and Intel Core Duo processors and later processors) is a 64-bit counter that is set to 0 following a RESET of
the processor."

Does a reset only occur when the system is rebooted? I mentioned the reset in the documentation here to be very specific, but if reset is always the same as boot then I agree it makes sense to change it to "nanoseconds since boot".

I'll add in the documentation that the nanoseconds being referred to here are from the the sched_clock and add the link you shared for reference.

74

Agreed, will revert back to the plain SP.

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

257

I agree that in its current state this isn't acting as a Get* function at all. However, after the comments @wallace left above, this function acts more like a Get* method as it returns the value of SP inside of the g_tsc_rate to be stored by tsc_rate

@davidca in point 3, are you suggesting that we move this field to be a member variable of IntelPTManager as opposed to a static variable because these conversion params change and thus should be fetched for each instance of the class?

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

214

Definitely, added that to the list of planned tests (in addition to malformed response JSON)

[jj10306]

Addressed most of the previous diff's comments (other than the ones from @wallace and @davidca that were explicitly mentioned in my previous comment). The naming of the conversion values is currently inconsistent, but I will update the naming and make it consistent across all the new changes once the name is agreed upon.

• Add client and server side caching of conversion values
• Update DecodedThread to allow for access to the conversion values from the TraceCursor
• Add GetNanos (to be renamed) API to TraceCursor to allow for conversion of a trace instruction's TSC value to nanoseconds
• Update trace schema and trace save commands to accommodate schema changes
• Add resource_handle namespace to allow for reuse of file descriptor and munmap resource handles
• Rename IntelPTManager to IntelPTCollector

[wallace]

lldb/docs/lldb-gdb-remote.txt

455

The ? After the key name makes Optional<> redundant. Just keep the ?

457

perf-linux might be a better name

458

All the supported kinds must be present below in the documentation, so no need to mention c++ classes here

lldb/include/lldb/Target/TraceCursor.h

193 ↗

(On Diff #413985)

What about just naming it GetTimestamp and return std::chrono::nanoseconds? That way we use c++ time conversion libraries and we don't include the time granularity in the name

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

47

This class is generic, so better not enforce the meaning of the zero tsc. Each trace plugin might be opinionated regarding this timestamp

65

Return a std:: Chrono type. You might want rename this to ToWallTime

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

53

Nice

218

Now that we don't have caching, try to move this method to Process Linux, as an static, so that others can use that method more easily.

239

We don't need caching anymore. Just calculate it every time we request the state, following the information that David gave that the rate might change over time.

[jj10306]

lldb/include/lldb/Target/TraceCursor.h

193 ↗

(On Diff #413985)

sgtm - do you think the GetTimestampCounter API's name should remain the same or change it to something like GetTsc? This file is trace agnostic so tying it to TSC could be confusing since, afaiu, TSC is intel specific, but I noticed the docs of that method mention "TSC", so curious to hear your thoughts.

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

44

Bumping this discussion related to naming

47

Good point. Given that this class is generic, would it make more sense to move it from this trace specific file TraceIntelPTGDBRemotePackets.h to TraceGDBRemotePackets.h since that file is trace agnostic?

[wallace]

The main change is to make the counter conversion generic, so that we don't need to add more APIs in the future. Besides that, you don't need to make any drastic change. Good job so far!

lldb/docs/lldb-gdb-remote.txt

455

let's make this more generic for any kind of counter we might want to include in a trace, including ones that could come from PT_WRITE, so let's call it counter_conversion

455–463

468–494

someone who wants to know more about these fields can simply open the perf_event documentation, so let's just point to it to reduce the amount of text here

lldb/include/lldb/Target/Trace.h

312

json_string is not a good name. Let's call it json_response

lldb/include/lldb/Target/TraceCursor.h

183–190 ↗

(On Diff #413985)

refactor this into a new function generic for all possible counters

you will need to create a new enum in lldb-enumerations.h

enum TraceCounter {

// Timestamp counter (TSC), like the one offered by Intel CPUs.
eTraceCounterTSC,

};

193 ↗

(On Diff #413985)

just replied above about having a generic method for all kinds of counter. Regarding this one, let's refactor it into

// Get the timestamp associated with the current instruction.
//
// Each trace plug-in might use a different 0 timestamp, e.g. time since last clock reset, time since the program started, etc.
// Also, it might happen that only some instructions of the entire trace have a timestamp associated with them.
//
//   \return
//      The timestamp associated with the current instruction, or llvm::None if not available.
virtual llvm::Optional<std::chrono::nanoseconds> GetTimestamp() = 0;

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

47

I imagine that with generic counter conversions we can't have a simple class that works for everything, but we might be able to do this:

template<typename ToType>
class TraceCounterConversion {
  virtual ~TraceCounterConversion() = default;
  virtual ToType ToNanos(uint64_t raw_counter) = 0;
  virtual llvm::json::Value toJSON() = 0;
}

also move it to TraceGDBRemotePackets as you mentioned.

Then the using statement from below could be specific for TSCs

using TraceTSCCounterRateSP = std::shared_ptr<TraceCounterConversion<uint64_t>> ;

That should work, as the intel pt plugin might explicit want a conversion type to uint64_t for its time conversions. Other hypothetical counters might be converted to double or int64_t, for example.

61

class LinuxPerfTscConversion: public TraceCounterConversion<uint64_t> {

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

1

rename this file to IntelPTCollector

700

rename this to FetchTscRate and move it to a new file lldb/source/Plugins/Process/Linux/Perf.h
you might want to move all the resource_handle functions to that file as well

701

This is the incorrect logging type. Create a new logging type POSIXLog::Trace. Ptrace is the name of the low-level linux tool used for debugging programs. Also change the logging type of the TraceStart method to match this new one

715

append the message of the errno with std::strerror(errno)

now that i think of it, you don't need to log anything here. Just return descriptive error messages and the caller should decide what to do with the errors.

725–726

return the error. The caller should decide whether to fail or to ignore the error

728

include the strerror

739–740

don't log, just return the error

748–755

we don't have caching, so the code should be like

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

315 ↗

(On Diff #413985)

nice

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

94–99 ↗

(On Diff #413985)

instead of having the decoded thread hand the tsc conversion params all the way up to here, you can create a new method llvm::Optional<std::chrono::nanoseconds> GetTimestamp(uint64_t insn_index)

let's try to have this method as simple as possible and put the implementation details at a lower level when possible

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

34–39 ↗

(On Diff #413985)

lldb/source/Target/TraceInstructionDumper.cpp

188–191 ↗

(On Diff #413985)

just like the m_show_tsc boolean there, you should add a m_show_realtime boolean. We can print the times in milliseconds, just like

[123.23ms]

printing in nanoseconds might be too much granularity for being readable

[wallace]

lldb/docs/lldb-gdb-remote.txt

455

After some more thoughts, let's just call this field 'counters'. And we can put any information related to any kind of counters.

So, we have something like

"counters"?: [{

... The tsc conversion object

}]

[jj10306]

Due to the size and expanding scope of this diff, I'm going to split this into several smaller diffs.

lldb/docs/lldb-gdb-remote.txt

 //    "processBinaryData": [
 //      {
 //        "kind": <string>,
 //            Identifier for some binary data related to this process to
 //            fetch with the jLLDBTraceGetBinaryData packet.
 //        "size": <decimal integer>,
 //            Size in bytes of this thread data.
 //      },
-//    }]
+//    }],
+//    ... other parameters specific to the provided tracing type
 //  }
 //
 // NOTES
 //   - "traceThreads" includes all thread traced by both "process tracing" and
 //     "thread tracing".
 //
 // INTEL PT
 //
 //  Binary data kinds:
 //    - threadTraceBuffer: trace buffer for a thread.
 //    - cpuInfo: contents of the /proc/cpuinfo file.
+//  Additional parameters in the output schema:
+//
+//    tsc_conversion: {
+//      kind: "perf",
+//      time_mult: int,
+//      time_shift: int,
+//      time_zero: int
+//      |
+//      kind: "freq"
+//      freq_conversion: int,
+//    }
+
+}
 //----------------------------------------------------------------------
 
 send packet: jLLDBTraceGetState:{"type":<type>}]
 read packet: {...object}/E<error code>;AAAAAAAAA
 
 //----------------------------------------------------------------------
 // jLLDBTraceGetBinaryData
 //
 // BRIEF
 //  Get binary data given a trace technology and a data identifier.
 //  The input is specified as a JSON object and the response has the same format
 //  as the "binary memory read" (aka "x") packet. In case of failures, an error
 //  message is returned.
 //
 // SCHEMA
 //  The schema for the input is
 //
 //  {
 //   "type": <string>,
 //       Tracing technology name, e.g. intel-pt, arm-coresight.
 //   "kind": <string>,
 //       Identifier for the data.
 //   "tid"?: <Optional decimal>,

lldb/include/lldb/Target/Trace.h

protected:
   ///     A JSON object string with custom data depending on the trace
   ///     technology, or an \a llvm::Error in case of errors.
   llvm::Expected<std::string> GetLiveProcessState();
 
   /// Method to be overriden by the plug-in to refresh its own state.
   ///
   /// This is invoked by RefreshLiveProcessState when a new state is found.
   ///
-  /// \param[in] state
-  ///     The jLLDBTraceGetState response.
-  virtual void
-  DoRefreshLiveProcessState(llvm::Expected<TraceGetStateResponse> state) = 0;
+  /// \param[in] json_string
+  ///     String representation of the jLLDBTraceGetState response.
+  ///
+  /// \return
+  ///     Unique pointer to the packet response, nullptr if response parsing failed.
+  virtual std::unique_ptr<TraceGetStateResponse>
+  DoRefreshLiveProcessState(llvm::Expected<std::string> json_string) = 0;
 
   /// Method to be invoked by the plug-in to refresh the live process state.
   ///
   /// The result is cached through the same process stop.
   void RefreshLiveProcessState();
 
   uint32_t m_stop_id = LLDB_INVALID_STOP_ID;
   /// Process traced by this object if doing live tracing. Otherwise it's null.
   Process *m_live_process = nullptr;

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

 //===-- TraceIntelPTGDBRemotePackets.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_UTILITY_TRACEINTELPTGDBREMOTEPACKETS_H
 #define LLDB_UTILITY_TRACEINTELPTGDBREMOTEPACKETS_H
 
 #include "lldb/Utility/TraceGDBRemotePackets.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;
struct TraceIntelPTStartRequest : TraceStartRequest {
   /// then a "tracing" stop event is triggered.
   llvm::Optional<int64_t> processBufferSizeLimit;
 };
 
 bool fromJSON(const llvm::json::Value &value, TraceIntelPTStartRequest &packet,
               llvm::json::Path path);
 
 llvm::json::Value toJSON(const TraceIntelPTStartRequest &packet);
+
+/// TSC to nanoseconds conversion values defined in struct perf_event_mmap_page.
+/// See https://man7.org/linux/man-pages/man2/perf_event_open.2.html for more information.
+struct PerfTscConversionValues {
+  // units should be uint32_t, uint16_t, uint64_t, respectively but since this will be converted to json these must be int64_t.
+  // This would only possibly be problematic for m_time_zero.
+  // TODO: how should the above issue be handled? Currently blindly casting time_zero to narrower type.
+  int64_t m_time_mult;
+  int64_t m_time_shift;
+  int64_t m_time_zero;
+};
+
+/// TSC to nanosecond conversion.
+struct TscConverter {
+  virtual ~TscConverter() = default;
+  /// Convert TSC value to nanoseconds.
+  virtual uint64_t TscToNanos(uint64_t tsc) = 0;
+  virtual llvm::json::Value toJSON() = 0;
+};
+
+/// Conversion based on values define in perf_event_mmap_page.
+struct PerfTscConverter : TscConverter {
+  PerfTscConverter() = default;
+  PerfTscConverter(uint32_t time_mult, uint16_t time_shift, uint64_t time_zero) :
+    m_perf_conversion{time_mult, time_shift, static_cast<int64_t>(time_zero)} {}
+  uint64_t TscToNanos(uint64_t tsc) override;
+  llvm::json::Value toJSON() override;
+
+  PerfTscConversionValues m_perf_conversion;
+};
+
+/// Conversion based on frequency conversion value defined in sys/fs file(s).
+//struct FreqTscConverter : TscConverter {
+//  FreqTscConverter(uint64_t freq_conversion) = default;
+//  FreqTscConverter(uint64_t freq_conversion) : m_freq_conversion(freq_conversion) {}
+//  uint64_t TscToNanos(uint64_t tsc) override;
+//  uint64_t m_freq_conversion;
+//};
+
+/// jLLDBTraceGetState gdb-remote packet
+/// Contains additional information related to TSC -> nanosecond conversion.
+struct TraceIntelPTGetStateResponse : TraceGetStateResponse {
+  /// Implementor of `TscConverter` interface.
+  /// `nullptr` if no TscConverter exists.
+  std::shared_ptr<TscConverter> tsc_converter;
+};
+
+bool fromJSON(const llvm::json::Value &value, std::shared_ptr<TscConverter> &tsc_converter, llvm::json::Path path);
+
+bool fromJSON(const llvm::json::Value &value, TraceIntelPTGetStateResponse &packet, llvm::json::Path path);
+
+llvm::json::Value toJSON(const TraceIntelPTGetStateResponse &packet);
+
 /// \}
 
 } // namespace lldb_private
 
 #endif // LLDB_UTILITY_TRACEINTELPTGDBREMOTEPACKETS_H

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

class IntelPTThreadTrace {
 
   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;

 };
 
 /// Main class that manages intel-pt process and thread tracing.
 class IntelPTManager {
 public:
   IntelPTManager(lldb::pid_t pid) : m_pid(pid), m_thread_traces(pid) {}
 
   static bool IsSupported();
 
   /// If "process tracing" is enabled, then trace the given thread.
   llvm::Error OnThreadCreated(lldb::tid_t tid);
 
   /// Stops tracing a tracing upon a destroy event.
   llvm::Error OnThreadDestroyed(lldb::tid_t tid);
 
   /// Implementation of the jLLDBTraceStop packet
   llvm::Error TraceStop(const TraceStopRequest &request);
 
   /// Implementation of the jLLDBTraceStart packet
   ///
   /// \param[in] process_threads
   ///     A list of all threads owned by the process.
   llvm::Error TraceStart(const TraceIntelPTStartRequest &request,
                          const std::vector<lldb::tid_t> &process_threads);
 
   /// Implementation of the jLLDBTraceGetState packet
   llvm::Expected<llvm::json::Value> GetState() const;
 
   /// Implementation of the jLLDBTraceGetBinaryData packet
   llvm::Expected<std::vector<uint8_t>>
   GetBinaryData(const TraceGetBinaryDataRequest &request) const;
 
   /// Dispose of all traces
   void Clear();
 
+  static std::shared_ptr<TscConverter> tsc_converter;
+
 private:
   llvm::Error TraceStop(lldb::tid_t tid);
 
   /// Start tracing a specific thread.
   llvm::Error TraceStart(lldb::tid_t tid,
                          const TraceIntelPTStartRequest &request);
 
   llvm::Expected<const IntelPTThreadTrace &>

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>
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";
 
+std::shared_ptr<TscConverter> IntelPTManager::tsc_converter = nullptr;
+
 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.
if (base == MAP_FAILED) {
     return createStringError(inconvertibleErrorCode(),
                              "Meta buffer allocation failed");
   }
 
   m_mmap_meta = std::unique_ptr<perf_event_mmap_page, munmap_delete>(
       reinterpret_cast<perf_event_mmap_page *>(base),
       munmap_delete(buffer_size + page_size));
 
+  if (m_mmap_meta->cap_user_time_zero) {
+    IntelPTManager::tsc_converter = std::make_shared<PerfTscConverter>(PerfTscConverter(m_mmap_meta->time_mult, m_mmap_meta->time_shift, m_mmap_meta->time_zero));
+  }
+
   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) {
Error IntelPTManager::OnThreadDestroyed(lldb::tid_t tid) {
   return Error::success();
 }
 
 Expected<json::Value> IntelPTManager::GetState() const {
   Expected<ArrayRef<uint8_t>> cpu_info = IntelPTThreadTrace::GetCPUInfo();
   if (!cpu_info)
     return cpu_info.takeError();
 
-  TraceGetStateResponse state;
+  TraceIntelPTGetStateResponse state;
   state.processBinaryData.push_back(
       {"cpuInfo", static_cast<int64_t>(cpu_info->size())});
 
   std::vector<TraceThreadState> thread_states =
       m_thread_traces.GetThreadStates();
   state.tracedThreads.insert(state.tracedThreads.end(), thread_states.begin(),
                              thread_states.end());
 
   if (IsProcessTracingEnabled()) {
     thread_states = m_process_trace->GetThreadTraces().GetThreadStates();
     state.tracedThreads.insert(state.tracedThreads.end(), thread_states.begin(),
                                thread_states.end());
   }
+
+  state.tsc_converter = IntelPTManager::tsc_converter;
+
   return toJSON(state);
 }
 
 Expected<const IntelPTThreadTrace &>
 IntelPTManager::GetTracedThread(lldb::tid_t tid) const {
   if (IsProcessTracingEnabled() && m_process_trace->TracesThread(tid))
     return m_process_trace->GetThreadTraces().GetTracedThread(tid);
   return m_thread_traces.GetTracedThread(tid);

 
 bool IntelPTManager::IsProcessTracingEnabled() const {
   return (bool)m_process_trace;
 }
 
 void IntelPTManager::Clear() {
   ClearProcessTracing();
   m_thread_traces.Clear();
 }

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

 //===-- TraceIntelPT.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_TRACEINTELPT_H
 #define LLDB_SOURCE_PLUGINS_TRACE_INTEL_PT_TRACEINTELPT_H
 
 #include "IntelPTDecoder.h"
 #include "TraceIntelPTSessionFileParser.h"
 #include "lldb/Utility/FileSpec.h"
+#include "lldb/Utility/TraceIntelPTGDBRemotePackets.h"
 #include "lldb/lldb-types.h"
 #include "llvm/Support/raw_ostream.h"
 
 namespace lldb_private {
 namespace trace_intel_pt {
 
 class TraceIntelPT : public Trace {
 public:
public:
   llvm::StringRef GetSchema() override;
 
   lldb::TraceCursorUP GetCursor(Thread &thread) override;
 
   void DumpTraceInfo(Thread &thread, Stream &s, bool verbose) override;
 
   llvm::Optional<size_t> GetRawTraceSize(Thread &thread);
 
-  void DoRefreshLiveProcessState(
-      llvm::Expected<TraceGetStateResponse> state) override;
+  std::unique_ptr<TraceGetStateResponse> DoRefreshLiveProcessState(
+      llvm::Expected<std::string> json_string) override;
 
   bool IsTraced(lldb::tid_t tid) override;
 
   const char *GetStartConfigurationHelp() override;
 
   /// Start tracing a live process.
   ///
   /// \param[in] thread_buffer_size
private:
   DecodedThreadSP Decode(Thread &thread);
 
   /// It is provided by either a session file or a live process' "cpuInfo"
   /// binary data.
   llvm::Optional<pt_cpu> m_cpu_info;
   std::map<lldb::tid_t, std::unique_ptr<ThreadDecoder>> m_thread_decoders;
   /// Error gotten after a failed live process update, if any.
   llvm::Optional<std::string> m_live_refresh_error;
+  /// TSC to nano converter. nullptr if no conversion exists.
+  std::shared_ptr<TscConverter> m_tsc_converter;
 };
 
 } // namespace trace_intel_pt
 } // namespace lldb_private
 
 #endif // LLDB_SOURCE_PLUGINS_TRACE_INTEL_PT_TRACEINTELPT_H

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

 #include "CommandObjectTraceStartIntelPT.h"
 #include "DecodedThread.h"
 #include "TraceIntelPTConstants.h"
 #include "TraceIntelPTSessionFileParser.h"
 #include "TraceIntelPTSessionSaver.h"
 #include "lldb/Core/PluginManager.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/Target.h"
+#include "lldb/Utility/TraceGDBRemotePackets.h"
 #include "llvm/ADT/None.h"
+#include <memory>
 
 using namespace lldb;
 using namespace lldb_private;
 using namespace lldb_private::trace_intel_pt;
 using namespace llvm;
 
 LLDB_PLUGIN_DEFINE(TraceIntelPT)
 
if (!m_cpu_info) {
     else
       return cpu_info.takeError();
   }
   return *m_cpu_info;
 }
 
 Process *TraceIntelPT::GetLiveProcess() { return m_live_process; }
 
-void TraceIntelPT::DoRefreshLiveProcessState(
-    Expected<TraceGetStateResponse> state) {
+std::unique_ptr<TraceGetStateResponse> TraceIntelPT::DoRefreshLiveProcessState(
+    Expected<std::string> json_string) {
+
+  if (!json_string) {
+    m_live_refresh_error = toString(json_string.takeError());
+    return nullptr;
+  }
+
   m_thread_decoders.clear();
 
+  Expected<TraceIntelPTGetStateResponse> state =
+      json::parse<TraceIntelPTGetStateResponse>(*json_string, "TraceIntelPTGetStateResponse");
+
   if (!state) {
     m_live_refresh_error = toString(state.takeError());
-    return;
+    return nullptr;
   }
 
   for (const TraceThreadState &thread_state : state->tracedThreads) {
     Thread &thread =
         *m_live_process->GetThreadList().FindThreadByID(thread_state.tid);
     m_thread_decoders.emplace(
         thread_state.tid, std::make_unique<LiveThreadDecoder>(thread, *this));
   }
+  if (!m_tsc_converter && state->tsc_converter)
+    m_tsc_converter = state->tsc_converter;
+
+  return std::make_unique<TraceGetStateResponse>(state.get());
 }
 
 bool TraceIntelPT::IsTraced(lldb::tid_t tid) {
   RefreshLiveProcessState();
   return m_thread_decoders.count(tid);
 }
 
 // The information here should match the description of the intel-pt section

lldb/source/Target/Trace.cpp

 #include "lldb/Core/Module.h"
 #include "lldb/Core/PluginManager.h"
 #include "lldb/Symbol/Function.h"
 #include "lldb/Target/ExecutionContext.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/SectionLoadList.h"
 #include "lldb/Target/Thread.h"
 #include "lldb/Utility/Stream.h"
+#include "lldb/Utility/TraceGDBRemotePackets.h"
 
 using namespace lldb;
 using namespace lldb_private;
 using namespace llvm;
 
 // Helper structs used to extract the type of a trace session json without
 // having to parse the entire object.
 
void Trace::RefreshLiveProcessState() {
 
   uint32_t new_stop_id = m_live_process->GetStopID();
   if (new_stop_id == m_stop_id)
     return;
 
   m_stop_id = new_stop_id;
   m_live_thread_data.clear();
 
-  Expected<std::string> json_string = GetLiveProcessState();
-  if (!json_string) {
-    DoRefreshLiveProcessState(json_string.takeError());
-    return;
-  }
-  Expected<TraceGetStateResponse> live_process_state =
-      json::parse<TraceGetStateResponse>(*json_string, "TraceGetStateResponse");
-  if (!live_process_state) {
-    DoRefreshLiveProcessState(live_process_state.takeError());
-    return;
-  }
+  std::unique_ptr<TraceGetStateResponse> live_process_state = DoRefreshLiveProcessState(GetLiveProcessState());
 
+  if (live_process_state) {
     for (const TraceThreadState &thread_state :
         live_process_state->tracedThreads) {
       for (const TraceBinaryData &item : thread_state.binaryData)
         m_live_thread_data[thread_state.tid][item.kind] = item.size;
     }
 
     for (const TraceBinaryData &item : live_process_state->processBinaryData)
       m_live_process_data[item.kind] = item.size;
+  }
 
-  DoRefreshLiveProcessState(std::move(live_process_state));
 }
 
 uint32_t Trace::GetStopID() {
   RefreshLiveProcessState();
   return m_stop_id;
 }

lldb/source/Utility/TraceIntelPTGDBRemotePackets.cpp

 //===-- TraceIntelPTGDBRemotePackets.cpp ------------------------*- 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
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/Utility/TraceIntelPTGDBRemotePackets.h"
+#include "lldb/Utility/TraceGDBRemotePackets.h"
 
 using namespace llvm;
 using namespace llvm::json;
 
 namespace lldb_private {
 
 bool fromJSON(const json::Value &value, TraceIntelPTStartRequest &packet,
               Path path) {
json::Value toJSON(const TraceIntelPTStartRequest &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;
 }
 
+uint64_t PerfTscConverter::TscToNanos(uint64_t tsc) {
+  // conversion logic here
+  return 1;
+}
+
+bool fromJSON(const llvm::json::Value &value, std::shared_ptr<TscConverter> &tsc_converter, llvm::json::Path path) {
+  std::string tsc_converter_kind;
+  ObjectMapper o(value, path);
+
+  bool ret = o.map("kind", tsc_converter_kind);
+
+  if (tsc_converter_kind == "perf") {
+    std::shared_ptr<PerfTscConverter> perf_tsc_converter_sp = std::make_shared<PerfTscConverter>(PerfTscConverter());
+    ret = ret && o.map("time_mult", perf_tsc_converter_sp->m_perf_conversion.m_time_mult) && o.map("time_shift", perf_tsc_converter_sp->m_perf_conversion.m_time_shift) && o.map("time_zero", perf_tsc_converter_sp->m_perf_conversion.m_time_zero);
+    // should we check ret here?
+    tsc_converter = perf_tsc_converter_sp;
+  } else if (tsc_converter_kind == "freq") {
+    // TODO
+    tsc_converter = nullptr;
+  } else {
+    tsc_converter = nullptr;
+  }
+  return ret;
+}
+
+bool fromJSON(const json::Value &value, TraceIntelPTGetStateResponse &packet, Path path) {
+  ObjectMapper o(value, path);
+  bool base_bool = o && fromJSON(value, (TraceGetStateResponse &)packet, path) && o.map("tsc_conversion", packet.tsc_converter);
+  // call perftscconverter
+  // get an instance of perftscconverter and wrap it in optional<shared<
+  return base_bool;
+
+}
+
+llvm::json::Value PerfTscConverter::toJSON() {
+  return json::Value(json::Object{
+    {"kind", "perf"},
+    {"time_mult",m_perf_conversion.m_time_mult},
+    {"time_shift", m_perf_conversion.m_time_shift},
+    {"time_zero", m_perf_conversion.m_time_zero},
+  });
+}
+
+json::Value toJSON(const TraceIntelPTGetStateResponse &packet) {
+  json::Value base = toJSON((const TraceGetStateResponse &)packet);
+  if (packet.tsc_converter) {
+    json::Value tsc_converter_json = packet.tsc_converter->toJSON();
+    base.getAsObject()->try_emplace("tsc_conversion", std::move(tsc_converter_json));
+  }
+  return base;
+}
 } // namespace lldb_private