[trace][intelpt] Support system-wide tracing [21] - Support long numbers in JSON

[wallace]

Summary

llvm's JSON parser supports 64 bit integers, but other tools like the
ones written in JS don't support numbers that big, so we need to
represent these possibly big numbers as a string. This diff uses that to
represent addresses and tsc zero. The former is printed in hex for and
the latter in decimal string form. The schema was updated mentioning
that.

Besides that, I fixed some remaining issues and now all test pass. Before I wasn't running all tests because for some reason my computer reverted perf_paranoid to 1.

[jj10306]

lldb/source/Utility/TraceIntelPTGDBRemotePackets.cpp

25

should there be an option to write it as an integer or would the user just be expected to use a raw u64 in that case?

[wallace]

lldb/source/Utility/TraceIntelPTGDBRemotePackets.cpp

25

I'd prefer us to emit only string numbers, but to leave the option for external tools to emit non-string decimals

lldb/docs/lldb-gdb-remote.txt

 //    otherwise it's "thread tracing".
 //  - Each tracing technology can have different levels of support for "thread
 //    tracing" and "process tracing".
 //
 // INTEL-PT
 //  intel-pt supports both "thread tracing" and "process tracing".
 //
 //  "Process tracing" is implemented in two different ways. If the
-//  "perCoreTracing" option is false, then each thread is traced individually
+//  "perCpuTracing" option is false, then each thread is traced individually
 //  but managed by the same "process trace" instance. This means that the
 //  amount of trace buffers used is proportional to the number of running
 //  threads. This is the recommended option unless the number of threads is
-//  huge. If "perCoreTracing" is true, then each cpu core is traced invidually
+//  huge. If "perCpuTracing" is true, then each cpu core is traced invidually
 //  instead of each thread, which uses a fixed number of trace buffers, but
 //  might result in less data available for less frequent threads. See
-//  "perCoreTracing" below for more information.
+//  "perCpuTracing" below for more information.
 //
 //  Each actual intel pt trace buffer, either from "process tracing" or "thread
 //  tracing", is stored in an in-memory circular buffer, which keeps the most
 //  recent data.
 //
 //  Additional params in the input schema:
 //   {
 //     "iptTraceSize": <decimal integer>,

 //         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 */
-//     "perCoreTracing": <boolean>
+//     "perCpuTracing": <boolean>
 //         Instead of having an individual trace buffer per thread, this option
 //         triggers the collection on a per cpu core basis. This effectively
 //         traces the entire activity on all cores. At decoding time, in order
 //         to correctly associate a decoded instruction with a thread, the
 //         context switch trace of each core is needed, as well as a record per
 //         cpu indicating which thread was running on each core when tracing
 //         started. These secondary traces are correlated with the intel-pt
 //         trace by comparing TSC timestamps.
 //
 //         This option forces the capture of TSC timestamps (see "enableTsc").
 //
 //         Note: This option can't be used simulatenously with any other trace
 //         sessions because of its system-wide nature.
 //
 //     /* 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 thread or cpu core
 //         buffers for the current process, excluding the ones started with
 //         "thread tracing".
 //
-//         If "perCoreTracing" is false, whenever a thread is attempted to be
+//         If "perCpuTracing" is false, whenever a thread is attempted to be
 //         traced due to "process tracing" and the limit would be reached, the
 //         process is stopped with a "tracing" reason along with a meaningful
 //         description, so that the user can retrace the process if needed.
 //
-//         If "perCoreTracing" is true, then starting the system-wide trace
-//         session fails if all the individual per-core trace buffers require
+//         If "perCpuTracing" is true, then starting the system-wide trace
+//         session fails if all the individual per-cpu trace buffers require
 //         in total more memory that the limit impossed by this parameter.
 //   }
 //
 //  Notes:
 //   - Modifying the parameters of an existing trace is not supported. The user
 //     needs to stop the trace and start a new one.
 //   - If "process tracing" is attempted and there are individual threads
 //     already being traced with "thread tracing", these traces are left

lldb/include/lldb/Utility/TraceIntelPTGDBRemotePackets.h

 };
 
 bool fromJSON(const llvm::json::Value &value, TraceIntelPTStartRequest &packet,
               llvm::json::Path path);
 
 llvm::json::Value toJSON(const TraceIntelPTStartRequest &packet);
 /// \}
 
+/// Helper structure to help parse long numbers that can't
+/// be easily represented by a JSON number that is compatible with
+/// Javascript (52 bits) or that can also be represented as hex.
+///
+/// \{
+struct JSONUINT64 {
+  uint64_t value;
+};
+
+llvm::json::Value toJSON(const JSONUINT64 &uint64, bool hex);
+
+bool fromJSON(const llvm::json::Value &value, JSONUINT64 &uint64,
+              llvm::json::Path path);
+/// \}
+
 /// jLLDBTraceGetState gdb-remote packet
 /// \{
 
 /// TSC to wall time conversion values defined in the Linux perf_event_open API
 /// when the capibilities cap_user_time and cap_user_time_zero are set. See the
 /// See the documentation of `time_zero` in
 /// https://man7.org/linux/man-pages/man2/perf_event_open.2.html for more
 /// information.
struct LinuxPerfZeroTscConversion {
   /// \return
   ///   Nanosecond wall time.
   uint64_t ToNanos(uint64_t tsc) const;
 
   uint64_t ToTSC(uint64_t nanos) const;
 
   uint32_t time_mult;
   uint16_t time_shift;
-  uint64_t time_zero;
+  JSONUINT64 time_zero;
 };
 
 struct TraceIntelPTGetStateResponse : TraceGetStateResponse {
   /// The TSC to wall time conversion if it exists, otherwise \b nullptr.
   llvm::Optional<LinuxPerfZeroTscConversion> tsc_perf_zero_conversion;
 };
 
 bool fromJSON(const llvm::json::Value &value,

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

return createStringError(
         inconvertibleErrorCode(),
         "Thread %" PRIu64 " is not part of the target process", tid);
   return Error::success();
 }
 
 Error IntelPTMultiCoreTrace::TraceStop(lldb::tid_t tid) {
   return createStringError(inconvertibleErrorCode(),
                            "Can't stop tracing an individual thread when "
-                           "per-core process tracing is enabled.");
+                           "per-cpu process tracing is enabled.");
 }
 
 Expected<Optional<std::vector<uint8_t>>>
 IntelPTMultiCoreTrace::TryGetBinaryData(
     const TraceGetBinaryDataRequest &request) {
   if (!request.cpu_id)
     return None;
   auto it = m_traces_per_core.find(*request.cpu_id);

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

 
 #include "lldb/Utility/TraceIntelPTGDBRemotePackets.h"
 
 #include <memory>
 
 namespace lldb_private {
 namespace process_linux {
 
-/// Interface to be implemented by each 'process trace' strategy (per core, per
+/// Interface to be implemented by each 'process trace' strategy (per cpu, per
 /// thread, etc).
 class IntelPTProcessTrace {
 public:
   virtual ~IntelPTProcessTrace() = default;
 
   virtual void ProcessDidStop() {}
 
   virtual void ProcessWillResume() {}

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

if (Error mmap_err =
           perf_event->MmapMetadataAndBuffers(/*num_data_pages=*/0,
                                              /*num_aux_pages=*/0,
                                              /*data_buffer_write=*/false))
     return std::move(mmap_err);
 
   perf_event_mmap_page &mmap_metada = perf_event->GetMetadataPage();
   if (mmap_metada.cap_user_time && mmap_metada.cap_user_time_zero) {
     return LinuxPerfZeroTscConversion{
-        mmap_metada.time_mult, mmap_metada.time_shift, mmap_metada.time_zero};
+        mmap_metada.time_mult, mmap_metada.time_shift, {mmap_metada.time_zero}};
   } else {
     auto err_cap =
         !mmap_metada.cap_user_time ? "cap_user_time" : "cap_user_time_zero";
     std::string err_msg =
         llvm::formatv("Can't get TSC to real time conversion values. "
                       "perf_event capability '{0}' not supported.",
                       err_cap);
     return llvm::createStringError(llvm::inconvertibleErrorCode(), err_msg);

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

 #include <vector>
 
 namespace lldb_private {
 namespace trace_intel_pt {
 
 struct JSONModule {
   std::string system_path;
   llvm::Optional<std::string> file;
-  uint64_t load_address;
+  JSONUINT64 load_address;
   llvm::Optional<std::string> uuid;
 };
 
 struct JSONThread {
   uint64_t tid;
   llvm::Optional<std::string> ipt_trace;
 };
 

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

Optional<std::vector<lldb::cpu_id_t>> JSONTraceSession::GetCpuIds() {
   return cpu_ids;
 }
 
 json::Value toJSON(const JSONModule &module) {
   json::Object json_module;
   json_module["systemPath"] = module.system_path;
   if (module.file)
     json_module["file"] = *module.file;
-  json_module["loadAddress"] = module.load_address;
+  json_module["loadAddress"] = toJSON(module.load_address, true);
   if (module.uuid)
     json_module["uuid"] = *module.uuid;
   return std::move(json_module);
 }
 
 bool fromJSON(const json::Value &value, JSONModule &module, Path path) {
   ObjectMapper o(value, path);
   return o && o.map("systemPath", module.system_path) &&

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

auto do_parse = [&]() -> Error {
     Status error;
     ModuleSP module_sp =
         target.GetOrCreateModule(module_spec, /*notify*/ false, &error);
 
     if (error.Fail())
       return error.ToError();
 
     bool load_addr_changed = false;
-    module_sp->SetLoadAddress(target, module.load_address, false,
+    module_sp->SetLoadAddress(target, module.load_address.value, false,
                               load_addr_changed);
     return Error::success();
   };
   if (Error err = do_parse())
     return createStringError(
         inconvertibleErrorCode(), "Error when parsing module %s. %s",
         module.system_path.c_str(), toString(std::move(err)).c_str());
   return Error::success();
"processes": [
         }
       ],
       "modules": [
         {
           "systemPath": string,
               // Original path of the module at runtime.
           "file"?: string,
               // Path to a copy of the file if not available at "systemPath".
-          "loadAddress": integer,
+          "loadAddress": integer | string decimal | hex string,
               // Lowest address of the sections of the module loaded on memory.
           "uuid"?: string,
               // Build UUID for the file for sanity checks.
         }
       ]
     }
   ],
   "cpus"?: [
StringRef TraceIntelPTSessionFileParser::GetSchema() {
   ],
   "tscPerfZeroConversion"?: {
     // Values used to convert between TSCs and nanoseconds. See the time_zero
     // section in https://man7.org/linux/man-pages/man2/perf_event_open.2.html
     // for for information.
 
     "timeMult": integer,
     "timeShift": integer,
-    "timeZero": integer,
+    "timeZero": integer | string decimal | hex string,
   }
 }
 
 Notes:
 
 - All paths are either absolute or relative to folder containing the session file.
 - "cpus" is provided if and only if processes[].threads[].iptTrace is not provided.
 - "tscPerfZeroConversion" must be provided if "cpus" is provided.

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

for (size_t i = 0; i < module_list.GetSize(); ++i) {
     sys::fs::create_directories(path_to_copy_module.GetDirectory().AsCString());
 
     if (std::error_code ec = llvm::sys::fs::copy_file(
             system_path, path_to_copy_module.GetPath()))
       return createStringError(
           inconvertibleErrorCode(),
           formatv("couldn't write to the file. {0}", ec.message()));
 
-    json_modules.push_back(JSONModule{system_path,
-                                      path_to_copy_module.GetPath(), load_addr,
-                                      module_sp->GetUUID().GetAsString()});
+    json_modules.push_back(
+        JSONModule{system_path, path_to_copy_module.GetPath(),
+                   JSONUINT64{load_addr}, module_sp->GetUUID().GetAsString()});
   }
   return json_modules;
 }
 
 /// Build the processes section of the trace session description file. Besides
 /// returning the processes information, this method saves to disk all modules
 /// and raw traces corresponding to the traced threads of the given process.
 ///

lldb/source/Utility/TraceIntelPTGDBRemotePackets.cpp

 const char *IntelPTDataKinds::kIptTrace = "iptTrace";
 const char *IntelPTDataKinds::kPerfContextSwitchTrace =
     "perfContextSwitchTrace";
 
 bool TraceIntelPTStartRequest::IsPerCpuTracing() const {
   return per_cpu_tracing.getValueOr(false);
 }
 
+json::Value toJSON(const JSONUINT64 &uint64, bool hex) {
+  if (hex)
+    return json::Value(formatv("{0:x+}", uint64.value));
+  else
+    return json::Value(formatv("{0}", uint64.value));
+}
+
+bool fromJSON(const json::Value &value, JSONUINT64 &uint64, Path path) {
+  if (Optional<uint64_t> val = value.getAsUINT64()) {
+    uint64.value = *val;
+    return true;
+  } else if (Optional<StringRef> val = value.getAsString()) {
+    if (!val->getAsInteger(/*radix=*/0, uint64.value))
+      return true;
+    path.report("invalid string number");
+  }
+  path.report("invalid number or string number");
+  return false;
+}
+
 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.enable_tsc) ||
-      !o.map("psbPeriod", packet.psb_period) ||
-      !o.map("iptTraceSize", packet.ipt_trace_size))
+  if (!(o && fromJSON(value, (TraceStartRequest &)packet, path) &&
+        o.map("enableTsc", packet.enable_tsc) &&
+        o.map("psbPeriod", packet.psb_period) &&
+        o.map("iptTraceSize", packet.ipt_trace_size)))
     return false;
 
   if (packet.IsProcessTracing()) {
     if (!o.map("processBufferSizeLimit", packet.process_buffer_size_limit) ||
         !o.map("perCpuTracing", packet.per_cpu_tracing))
       return false;
   }
   return true;
json::Value toJSON(const TraceIntelPTStartRequest &packet) {
   obj.try_emplace("perCpuTracing", packet.per_cpu_tracing);
   return base;
 }
 
 uint64_t LinuxPerfZeroTscConversion::ToNanos(uint64_t tsc) const {
   uint64_t quot = tsc >> time_shift;
   uint64_t rem_flag = (((uint64_t)1 << time_shift) - 1);
   uint64_t rem = tsc & rem_flag;
-  return time_zero + quot * time_mult + ((rem * time_mult) >> time_shift);
+  return time_zero.value + quot * time_mult + ((rem * time_mult) >> time_shift);
 }
 
 uint64_t LinuxPerfZeroTscConversion::ToTSC(uint64_t nanos) const {
-  uint64_t time = nanos - time_zero;
+  uint64_t time = nanos - time_zero.value;
   uint64_t quot = time / time_mult;
   uint64_t rem = time % time_mult;
   return (quot << time_shift) + (rem << time_shift) / time_mult;
 }
 
 json::Value toJSON(const LinuxPerfZeroTscConversion &packet) {
   return json::Value(json::Object{
       {"timeMult", packet.time_mult},
       {"timeShift", packet.time_shift},
-      {"timeZero", packet.time_zero},
+      {"timeZero", toJSON(packet.time_zero, /*hex=*/false)},
   });
 }
 
 bool fromJSON(const json::Value &value, LinuxPerfZeroTscConversion &packet,
               json::Path path) {
   ObjectMapper o(value, path);
-  uint64_t time_mult, time_shift, time_zero;
-  if (!o || !o.map("timeMult", time_mult) || !o.map("timeShift", time_shift) ||
-      !o.map("timeZero", time_zero))
+  uint64_t time_mult, time_shift;
+  if (!(o && o.map("timeMult", time_mult) && o.map("timeShift", time_shift) &&
+        o.map("timeZero", packet.time_zero)))
     return false;
   packet.time_mult = time_mult;
-  packet.time_zero = time_zero;
   packet.time_shift = time_shift;
   return true;
 }
 
 bool fromJSON(const json::Value &value, TraceIntelPTGetStateResponse &packet,
               json::Path path) {
   ObjectMapper o(value, path);
   return o && fromJSON(value, (TraceGetStateResponse &)packet, path) &&

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

def testLoadMultiCoreTrace(self):
         self.expect("thread trace dump instructions 2 -t",
           substrs=["19521: [tsc=0x008fb5211c143fd8] error: expected tracing enabled event",
                    "m.out`foo() + 65 at multi_thread.cpp:12:21",
                    "19520: [tsc=0x008fb5211bfbc69e] 0x0000000000400ba7    jg     0x400bb3"])
         self.expect("thread trace dump instructions 3 -t",
           substrs=["67910: [tsc=0x008fb5211bfdf270] 0x0000000000400bd7    addl   $0x1, -0x4(%rbp)",
                    "m.out`bar() + 26 at multi_thread.cpp:20:6"])
 
+    def testLoadMultiCoreTraceWithStringNumbers(self):
+        src_dir = self.getSourceDir()
+        trace_definition_file = os.path.join(src_dir, "intelpt-multi-core-trace", "trace_with_string_numbers.json")
+        self.expect("trace load -v " + trace_definition_file, substrs=["intel-pt"])
+        self.expect("thread trace dump instructions 2 -t",
+          substrs=["19521: [tsc=0x008fb5211c143fd8] error: expected tracing enabled event",
+                   "m.out`foo() + 65 at multi_thread.cpp:12:21",
+                   "19520: [tsc=0x008fb5211bfbc69e] 0x0000000000400ba7    jg     0x400bb3"])
+        self.expect("thread trace dump instructions 3 -t",
+          substrs=["67910: [tsc=0x008fb5211bfdf270] 0x0000000000400bd7    addl   $0x1, -0x4(%rbp)",
+                   "m.out`bar() + 26 at multi_thread.cpp:20:6"])
+
     def testLoadMultiCoreTraceWithMissingThreads(self):
         src_dir = self.getSourceDir()
         trace_definition_file = os.path.join(src_dir, "intelpt-multi-core-trace", "trace_missing_threads.json")
         self.expect("trace load -v " + trace_definition_file, substrs=["intel-pt"])
         self.expect("thread trace dump instructions 3 -t",
           substrs=["19521: [tsc=0x008fb5211c143fd8] error: expected tracing enabled event",
                    "m.out`foo() + 65 at multi_thread.cpp:12:21",
                    "19520: [tsc=0x008fb5211bfbc69e] 0x0000000000400ba7    jg     0x400bb3"])

lldb/test/API/commands/trace/intelpt-multi-core-trace/trace_with_string_numbers.json

+{
+  "cpus": [
+    {
+      "contextSwitchTrace": "cores/45.perf_context_switch_trace",
+      "id": 45,
+      "iptTrace": "cores/45.intelpt_trace"
+    },
+    {
+      "contextSwitchTrace": "cores/51.perf_context_switch_trace",
+      "id": 51,
+      "iptTrace": "cores/51.intelpt_trace"
+    }
+  ],
+  "cpuInfo": {
+    "family": 6,
+    "model": 85,
+    "stepping": 4,
+    "vendor": "GenuineIntel"
+  },
+  "processes": [
+    {
+      "modules": [
+        {
+          "file": "modules/m.out",
+          "systemPath": "/tmp/m.out",
+          "loadAddress": "4194304",
+          "uuid": "AEFB0D59-233F-80FF-6D3C-4DED498534CF-11017B3B"
+        }
+      ],
+      "pid": 3497234,
+      "threads": [
+        {
+          "tid": 3497234
+        },
+        {
+          "tid": 3497496
+        },
+        {
+          "tid": 3497497
+        }
+      ]
+    }
+  ],
+  "tscPerfZeroConversion": {
+    "timeMult": 1076264588,
+    "timeShift": 31,
+    "timeZero": "18433473881008870804"
+  },
+  "type": "intel-pt"
+}