new api

[wallace]

.

[wallace]

.

lldb/bindings/interface/SBStructuredData.i

public:
         lldb::SBError
         GetAsJSON(lldb::SBStream &stream) const;
 
         lldb::SBError
         GetDescription(lldb::SBStream &stream) const;
 
         lldb::SBError
         SetFromJSON(lldb::SBStream &stream);
+
+        lldb::SBError
+        SetFromJSON(const char *json);
     };
 }

lldb/bindings/interface/SBTarget.i

#endif
     lldb::SBValue
     EvaluateExpression (const char *expr);
 
     lldb::SBValue
     EvaluateExpression (const char *expr, const lldb::SBExpressionOptions &options);
 
     STRING_EXTENSION_LEVEL(SBTarget, lldb::eDescriptionLevelBrief)
 
+    lldb::SBTrace
+    GetTrace ();
+
+    lldb::SBTrace
+    GetTraceOrCreate (lldb::SBError &error);
+
 #ifdef SWIGPYTHON
     %pythoncode %{
         class modules_access(object):
             '''A helper object that will lazily hand out lldb.SBModule objects for a target when supplied an index, or by full or partial path.'''
             def __init__(self, sbtarget):
                 self.sbtarget = sbtarget
 
             def __len__(self):

lldb/bindings/interface/SBTrace.i

 //===-- SWIG Interface for SBTrace.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
 //
 //===----------------------------------------------------------------------===//
 
 namespace lldb {
 
 %feature("docstring",
 "Represents a processor trace."
 ) SBTrace;
 class LLDB_API SBTrace {
 public:
   SBTrace();
+
   size_t GetTraceData(SBError &error, void *buf,
                       size_t size, size_t offset,
                       lldb::tid_t thread_id);
 
-  size_t GetMetaData(SBError &error, void *buf,
-                     size_t size, size_t offset,
-                     lldb::tid_t thread_id);
+  SBError StartProcess();
+
+  SBError StartProcess(const SBStructuredData &configuration);
+
+  SBError StartThread(const SBThread &thread);
+
+  SBError StartThread(const SBThread &thread, const SBStructuredData &configuration);
+
+  SBError StopProcess();
+
+  SBError StopThread(const SBThread &thread);
+
+  explicit operator bool() const;
+
+  bool IsValid();
 
+  // legacy
   void StopTrace(SBError &error,
                  lldb::tid_t thread_id);
 
+  // deprecated
   void GetTraceConfig(SBTraceOptions &options,
                       SBError &error);
 
+  // deprecated
   lldb::user_id_t GetTraceUID();
 
-  explicit operator bool() const;
-
-  bool IsValid();
-
+  // deprecated
+  size_t GetMetaData(SBError &error, void *buf,
+                     size_t size, size_t offset,
+                     lldb::tid_t thread_id);
 };
-} // namespace lldb
+} // namespace lldb
 

lldb/bindings/interface/SBTraceOptions.i

 //===-- SWIG Interface for SBTraceOptions -----------------------*- 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
 //
 //===----------------------------------------------------------------------===//
 
 namespace lldb {
 
 %feature("docstring",
-"Represents the possible options when doing processor tracing.
-
-See :py:class:`SBProcess.StartTrace`."
+"deprecated"
 ) SBTraceOptions;
+// deprecated
 class LLDB_API SBTraceOptions {
 public:
+  // deprecated
   SBTraceOptions();
 
+  // deprecated
   lldb::TraceType getType() const;
 
+  // deprecated
   uint64_t getTraceBufferSize() const;
 
+  // deprecated
   lldb::SBStructuredData getTraceParams(lldb::SBError &error);
 
+  // deprecated
   uint64_t getMetaDataBufferSize() const;
 
+  // deprecated
   void setTraceParams(lldb::SBStructuredData &params);
 
+  // deprecated
   void setType(lldb::TraceType type);
 
+  // deprecated
   void setTraceBufferSize(uint64_t size);
 
+  // deprecated
   void setMetaDataBufferSize(uint64_t size);
 
+  // deprecated
   void setThreadID(lldb::tid_t thread_id);
 
+  // deprecated
   lldb::tid_t getThreadID();
 
+  // deprecated
   explicit operator bool() const;
 
+  // deprecated
   bool IsValid();
 };
 }

lldb/docs/design/overview.rst

 
 Utility
 -------
 
 This module contains the lowest layers of LLDB. A lot of these classes don't
 really have anything to do with debugging -- they are just there because the
 higher layers of the debugger use these clasess to implement their
 functionality. Others are data structures used in many other parts of the
-debugger (TraceOptions). Most of the functionality in this module could be
-useful in an application that is not a debugger; however, providing a general
-purpose C++ library is an explicit non-goal of this module.
+debugger. Most of the functionality in this module could be useful in an
+application that is not a debugger; however, providing a general purpose C++
+library is an explicit non-goal of this module.
 
 This module provides following functionality:
 
 - Abstract path manipulation (FileSpec)
 - Architecture specification
 - Data buffers (DataBuffer, DataEncoder, DataExtractor)
 - Logging
 - Structured data manipulation (JSON)
 - Streams
 - Timers
 
 For historic reasons, some of this functionality overlaps that which is
 provided by the LLVM support library.

lldb/include/lldb/API/SBProcess.h

public:
   lldb::SBBroadcaster GetBroadcaster() const;
 
   static const char *GetBroadcasterClass();
 
   bool GetDescription(lldb::SBStream &description);
 
   SBStructuredData GetExtendedCrashInformation();
 
-  /// Start Tracing with the given SBTraceOptions.
-  ///
-  /// \param[in] options
-  ///     Class containing trace options like trace buffer size, meta
-  ///     data buffer size, TraceType and any custom parameters
-  ///     {formatted as a JSON Dictionary}. In case of errors in
-  ///     formatting, an error would be reported.
-  ///     It must be noted that tracing options such as buffer sizes
-  ///     or other custom parameters passed maybe invalid for some
-  ///     trace technologies. In such cases the trace implementations
-  ///     could choose to either throw an error or could round off to
-  ///     the nearest valid options to start tracing if the passed
-  ///     value is not supported. To obtain the actual used trace
-  ///     options please use the GetTraceConfig API. For the custom
-  ///     parameters, only the parameters recognized by the target
-  ///     would be used and others would be ignored.
-  ///
-  /// \param[out] error
-  ///     An error explaining what went wrong.
-  ///
-  /// \return
-  ///     A SBTrace instance, which should be used
-  ///     to get the trace data or other trace related operations.
+  /// Deprecated
   lldb::SBTrace StartTrace(SBTraceOptions &options, lldb::SBError &error);
 
   uint32_t GetNumSupportedHardwareWatchpoints(lldb::SBError &error) const;
 
   /// Load a shared library into this process.
   ///
   /// \param[in] remote_image_spec
   ///     The path for the shared library on the target what you want
uint32_t LoadImage(const lldb::SBFileSpec &local_image_spec,
                      const lldb::SBFileSpec &remote_image_spec,
                      lldb::SBError &error);
 
   /// Load a shared library into this process, starting with a
   /// library name and a list of paths, searching along the list of
   /// paths till you find a matching library.
   ///
   /// \param[in] image_spec
-  ///     The name of the shared library that you want to load.  
+  ///     The name of the shared library that you want to load.
   ///     If image_spec is a relative path, the relative path will be
   ///     appended to the search paths.
   ///     If the image_spec is an absolute path, just the basename is used.
   ///
   /// \param[in] paths
-  ///     A list of paths to search for the library whose basename is 
+  ///     A list of paths to search for the library whose basename is
   ///     local_spec.
   ///
   /// \param[out] loaded_path
   ///     If the library was found along the paths, this will store the
   ///     full path to the found library.
   ///
   /// \param[out] error
   ///     An error object that gets filled in with any errors that
   ///     might occur when trying to search for the shared library.
   ///
   /// \return
   ///     A token that represents the shared library that can be
   ///     later passed to UnloadImage. A value of
   ///     LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
   ///     library can't be opened.
   uint32_t LoadImageUsingPaths(const lldb::SBFileSpec &image_spec,
                                SBStringList &paths,
-                               lldb::SBFileSpec &loaded_path, 
+                               lldb::SBFileSpec &loaded_path,
                                lldb::SBError &error);
 
   lldb::SBError UnloadImage(uint32_t image_token);
 
   lldb::SBError SendEventData(const char *data);
 
   /// Return the number of different thread-origin extended backtraces
   /// this process can support.

lldb/include/lldb/API/SBStructuredData.h

 
 class SBStructuredData {
 public:
   SBStructuredData();
 
   SBStructuredData(const lldb::SBStructuredData &rhs);
 
   SBStructuredData(const lldb::EventSP &event_sp);
-  
   SBStructuredData(lldb_private::StructuredDataImpl *impl);
 
   ~SBStructuredData();
 
   lldb::SBStructuredData &operator=(const lldb::SBStructuredData &rhs);
 
   explicit operator bool() const;
 
   bool IsValid() const;
 
   lldb::SBError SetFromJSON(lldb::SBStream &stream);
 
+  lldb::SBError SetFromJSON(const char *json);
+
   void Clear();
 
   lldb::SBError GetAsJSON(lldb::SBStream &stream) const;
 
   lldb::SBError GetDescription(lldb::SBStream &stream) const;
 
   /// Return the type of data in this data structure
   lldb::StructuredDataType GetType() const;
-  
   /// Return the size (i.e. number of elements) in this data structure
   /// if it is an array or dictionary type. For other types, 0 will be
   //  returned.
   size_t GetSize() const;
 
   /// Fill keys with the keys in this object and return true if this data
   /// structure is a dictionary.  Returns false otherwise.
    bool GetKeys(lldb::SBStringList &keys) const;
-  
   /// Return the value corresponding to a key if this data structure
   /// is a dictionary type.
   lldb::SBStructuredData GetValueForKey(const char *key) const;
 
   /// Return the value corresponding to an index if this data structure
   /// is array.
   lldb::SBStructuredData GetItemAtIndex(size_t idx) const;
 
protected:
   friend class SBDebugger;
   friend class SBTarget;
   friend class SBProcess;
   friend class SBThread;
   friend class SBThreadPlan;
   friend class SBBreakpoint;
   friend class SBBreakpointLocation;
   friend class SBBreakpointName;
+  friend class SBTrace;
 
   StructuredDataImplUP m_impl_up;
 };
 } // namespace lldb
 
 #endif // LLDB_API_SBSTRUCTUREDDATA_H

lldb/include/lldb/API/SBTarget.h

lldb::SBBreakpoint BreakpointCreateBySourceRegex(
       const SBFileSpecList &source_file, const SBStringList &func_names);
 
   lldb::SBBreakpoint BreakpointCreateForException(lldb::LanguageType language,
                                                   bool catch_bp, bool throw_bp);
 
   lldb::SBBreakpoint BreakpointCreateByAddress(addr_t address);
 
   lldb::SBBreakpoint BreakpointCreateBySBAddress(SBAddress &address);
-  
   /// Create a breakpoint using a scripted resolver.
   ///
   /// \param[in] class_name
   ///    This is the name of the class that implements a scripted resolver.
   ///
   /// \param[in] extra_args
   ///    This is an SBStructuredData object that will get passed to the
-  ///    constructor of the class in class_name.  You can use this to 
-  ///    reuse the same class, parametrizing with entries from this 
+  ///    constructor of the class in class_name.  You can use this to
+  ///    reuse the same class, parametrizing with entries from this
   ///    dictionary.
   ///
   /// \param module_list
-  ///    If this is non-empty, this will be used as the module filter in the 
+  ///    If this is non-empty, this will be used as the module filter in the
   ///    SearchFilter created for this breakpoint.
   ///
   /// \param file_list
-  ///    If this is non-empty, this will be used as the comp unit filter in the 
+  ///    If this is non-empty, this will be used as the comp unit filter in the
   ///    SearchFilter created for this breakpoint.
   ///
   /// \return
   ///     An SBBreakpoint that will set locations based on the logic in the
   ///     resolver's search callback.
   lldb::SBBreakpoint BreakpointCreateFromScript(
       const char *class_name,
       SBStructuredData &extra_args,
public:
   lldb::addr_t GetStackRedZoneSize();
 
   bool IsLoaded(const lldb::SBModule &module) const;
 
   lldb::SBLaunchInfo GetLaunchInfo() const;
 
   void SetLaunchInfo(const lldb::SBLaunchInfo &launch_info);
 
+  /// Get the \a SBTrace object containing processor trace information of this
+  /// target.
+  ///
+  /// \return
+  ///   The trace object. It might be undefined.
+  lldb::SBTrace GetTrace();
+
+  /// Similar to \a GetTrace, but this also tries to create a \a Trace object
+  /// if not available using the default supported tracing technology for
+  /// this process.
+  ///
+  /// \param[out] error
+  ///     An error explaining why the trace couldn't be created.
+  lldb::SBTrace GetTraceOrCreate(SBError &error);
+
 protected:
   friend class SBAddress;
   friend class SBBlock;
   friend class SBBreakpointList;
   friend class SBBreakpointNameImpl;
   friend class SBDebugger;
   friend class SBExecutionContext;
   friend class SBFunction;

lldb/include/lldb/API/SBThread.h

private:
   friend class SBExecutionContext;
   friend class SBFrame;
   friend class SBProcess;
   friend class SBDebugger;
   friend class SBValue;
   friend class lldb_private::QueueImpl;
   friend class SBQueueItem;
   friend class SBThreadPlan;
+  friend class SBTrace;
 
   void SetThread(const lldb::ThreadSP &lldb_object_sp);
 
   SBError ResumeNewPlan(lldb_private::ExecutionContext &exe_ctx,
                         lldb_private::ThreadPlan *new_plan);
 
   lldb::ExecutionContextRefSP m_opaque_sp;
 
   lldb_private::Thread *operator->();
 
   lldb_private::Thread *get();
 };
 
 } // namespace lldb
 
 #endif // LLDB_API_SBTHREAD_H

lldb/include/lldb/API/SBTrace.h

 #include "lldb/API/SBError.h"
 
 class TraceImpl;
 
 namespace lldb {
 
 class LLDB_API SBTrace {
 public:
+  /// Default constructor for an invalid Trace object.
   SBTrace();
+
+  SBTrace(const lldb::TraceSP &trace_sp);
+
   /// Obtain the trace data as raw bytes.
   ///
   /// \param[out] error
   ///     An error explaining what went wrong.
   ///
   /// \param[in] buf
   ///     Buffer to write the trace data to.
   ///
public:
   ///     such a scenario to select the trace data for a specific
   ///     thread.
   ///
   /// \return
   ///     The size of the trace data effectively read by the API call.
   size_t GetTraceData(SBError &error, void *buf, size_t size, size_t offset = 0,
                       lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
 
-  /// Obtain any meta data as raw bytes for the tracing instance.
-  /// The input parameter definition is similar to the previous
-  /// function.
-  size_t GetMetaData(SBError &error, void *buf, size_t size, size_t offset = 0,
-                     lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
+  /// Start tracing a live process using a default configuration.
+  ///
+  /// \return
+  ///     An error explaining any failures.
+  SBError StartProcess();
 
-  /// Stop the tracing instance. Stopping the trace will also
-  /// lead to deletion of any gathered trace data.
+  /// Start tracing a live process using a provided configuration.
   ///
-  /// \param[out] error
-  ///     An error explaining what went wrong.
+  /// \param[in] configuration
+  ///     Dictionary object with custom fields for the corresponding trace
+  ///     technology.
+  ///
+  ///     If a parameter is not specified, a default value will be used.
+  ///
+  ///     For intel-pt:
+  ///       - int threadBufferSize (defaults to 4096 bytes):
+  ///         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.
+  ///       - int processBufferSizeLimit (defaults to 500 MB):
+  ///         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 \a SBTrace::StartThread().
+  ///         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.
+  ///
+  /// \return
+  ///     An error explaining any failures.
+  SBError StartProcess(const SBStructuredData &configuration);
+
+  /// Start tracing a live thread using a default configuration.
+  ///
+  /// \return
+  ///     An error explaining any failures.
+  SBError StartThread(const SBThread &thread);
+
+  /// Start tracing a live thread using a provided configuration.
+  ///
+  /// \param[in] configuration
+  ///     Dictionary object with custom fields for the corresponding trace
+  ///     technology.
+  ///
+  ///     If a parameter is not specified, a default value will be used.
+  ///
+  ///     For intel-pt:
+  ///       - int threadBufferSize (defaults to 4096 bytes):
+  ///         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.
+  ///
+  /// \return
+  ///     An error explaining any failures.
+  SBError StartThread(const SBThread &thread, const SBStructuredData &configuration);
+
+  /// Stop tracing a live process.
+  ///
+  /// \return
+  ///     An error explaining any failures.
+  SBError StopProcess();
+
+  /// Stop tracing a live thread.
+  ///
+  /// \return
+  ///     An error explaining any failures.
+  SBError StopThread(const SBThread &thread);
+
+  /// Legacy.
+  ///
+  /// Stop tracing for a thread or the entire process.
   ///
   /// \param[in] thread_id
-  ///     The trace id could map to a tracing instance for a thread
-  ///     or could also map to a group of threads being traced with
-  ///     the same trace options. A thread_id is normally optional
-  ///     except in the case of tracing a complete process and tracing
-  ///     needs to switched off on a particular thread.
-  ///     A situation could occur where initially a thread (lets say
-  ///     thread A) is being individually traced with a particular
-  ///     trace id and then tracing is started on the complete
-  ///     process, in this case thread A will continue without any
-  ///     change. All newly spawned threads would be traced with the
-  ///     trace id of the process.
-  ///     Now if the StopTrace API is called for the whole process,
-  ///     thread A will not be stopped and must be stopped separately.
+  ///     If \b LLDB_INVALID_THREAD_ID, stops tracing the given thread_id,
+  ///     otherwise stops tracing the entire process.
   void StopTrace(SBError &error,
                  lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
 
-  /// Get the trace configuration being used for the trace instance.
-  /// The threadid in the SBTraceOptions needs to be set when the
-  /// configuration used by a specific thread is being requested.
-  ///
-  /// \param[out] options
-  ///     The trace options actually used by the trace instance
-  ///     would be filled by the API.
+  /// Run the provided callback on the instructions of the trace of the given
+  /// thread.
   ///
-  /// \param[out] error
-  ///     An error explaining what went wrong.
-  void GetTraceConfig(SBTraceOptions &options, SBError &error);
-
-  lldb::user_id_t GetTraceUID();
+  /// The instructions will be traversed starting at the given \a position
+  /// sequentially until the callback returns \b false, in which case no more
+  /// instructions are inspected.
+  ///
+  /// The purpose of this method is to allow inspecting traced instructions
+  /// without exposing the internal representation of how they are stored on
+  /// memory.
+  ///
+  /// \param[in] thread
+  ///     The thread whose trace will be traversed.
+  ///
+  /// \param[in] start_position
+  ///     The instruction position to start iterating from.
+  ///
+  ///     This number can be negative, which means an offset from the end of the trace. E.g. -1 means the last instruction of the trace.
+  ///     When using negative start positions, the indices passed to the callback will be negative as well.
+  ///     This can be used by Trace plug-ins as a means to lazily parse the trace if the user is only interested in the last instructions.
+  ///
+  /// \param[in] direction
+  ///     If \b eTraceDirectionForwards, then then instructions will be
+  ///     traversed forwards chronologically, i.e. with incrementing indices. If
+  ///     \b eTraceDirectionBackwards, the traversal is done backwards
+  ///     chronologically, i.e. with decrementing indices.
+  ///
+  /// \param[in] callback
+  ///     The callback to execute on each instruction. If it returns \b false,
+  ///     the iteration stops.
+  SBError TraverseInstructions(SBThread thread, int start_position, lldb::TraceDirection direction, std::function<bool(int index, lldb::addr_t load_address)> callback);
 
   explicit operator bool() const;
 
   bool IsValid();
 
-protected:
-  typedef std::shared_ptr<TraceImpl> TraceImplSP;
-
-  friend class SBProcess;
-
-  void SetTraceUID(lldb::user_id_t uid);
-
-  TraceImplSP m_trace_impl_sp;
+  /// Deprecated
+  /// \{
+  size_t GetMetaData(SBError &error, void *buf, size_t size, size_t offset = 0,
+                     lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
 
-  lldb::ProcessSP GetSP() const;
+  void GetTraceConfig(SBTraceOptions &options, SBError &error);
 
-  void SetSP(const ProcessSP &process_sp);
+  lldb::user_id_t GetTraceUID();
+  /// \}
 
-  lldb::ProcessWP m_opaque_wp;
+protected:
+  lldb::TraceSP m_opaque_sp;
 };
 } // namespace lldb
 
 #endif // LLDB_API_SBTRACE_H

lldb/include/lldb/API/SBTraceOptions.h

 //===-- SBTraceOptions ------------------------------------------*- 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_API_SBTRACEOPTIONS_H
 #define LLDB_API_SBTRACEOPTIONS_H
 
 #include "lldb/API/SBDefines.h"
 
 namespace lldb {
 
+/// Deprecated
 class LLDB_API SBTraceOptions {
 public:
+  /// Deprecated
   SBTraceOptions();
 
+  /// Deprecated
   lldb::TraceType getType() const;
 
+  /// Deprecated
   uint64_t getTraceBufferSize() const;
 
-  /// The trace parameters consist of any custom parameters
-  /// apart from the generic parameters such as
-  /// TraceType, trace_buffer_size and meta_data_buffer_size.
-  /// The returned parameters would be formatted as a JSON Dictionary.
+  /// Deprecated
   lldb::SBStructuredData getTraceParams(lldb::SBError &error);
 
+  /// Deprecated
   uint64_t getMetaDataBufferSize() const;
 
-  /// SBStructuredData is meant to hold any custom parameters
-  /// apart from meta buffer size and trace size. They should
-  /// be formatted as a JSON Dictionary.
+  /// Deprecated
   void setTraceParams(lldb::SBStructuredData &params);
 
+  /// Deprecated
   void setType(lldb::TraceType type);
 
+  /// Deprecated
   void setTraceBufferSize(uint64_t size);
 
+  /// Deprecated
   void setMetaDataBufferSize(uint64_t size);
 
+  /// Deprecated
   void setThreadID(lldb::tid_t thread_id);
 
+  /// Deprecated
   lldb::tid_t getThreadID();
 
+  /// Deprecated
   explicit operator bool() const;
 
+  /// Deprecated
   bool IsValid();
 
 protected:
   friend class SBProcess;
   friend class SBTrace;
-
-  lldb::TraceOptionsSP m_traceoptions_sp;
 };
 }
 
 #endif // LLDB_API_SBTRACEOPTIONS_H

lldb/include/lldb/Target/Process.h

void PruneThreadPlans();
   /// one way to tell whether a feature is available.
   ///
   /// \return
   ///     The plugin if one is available for the specified feature;
   ///     otherwise, returns an empty shared pointer.
   lldb::StructuredDataPluginSP
   GetStructuredDataPlugin(ConstString type_name) const;
 
-  /// Deprecated
-  ///
-  /// Starts tracing with the configuration provided in options. To enable
-  /// tracing on the complete process the thread_id in the options should be
-  /// set to LLDB_INVALID_THREAD_ID. The API returns a user_id which is needed
-  /// by other API's that manipulate the trace instance. The handling of
-  /// erroneous or unsupported configuration is left to the trace technology
-  /// implementations in the server, as they could be returned as an error, or
-  /// rounded to a valid configuration to start tracing. In the later case the
-  /// GetTraceConfig should supply the actual used trace configuration.
-  virtual lldb::user_id_t StartTrace(const TraceOptions &options,
-                                     Status &error) {
-    error.SetErrorString("Not implemented");
-    return LLDB_INVALID_UID;
-  }
-
-  /// Deprecated
-  ///
-  /// Stops the tracing instance leading to deletion of the trace data. The
-  /// tracing instance is identified by the user_id which is obtained when
-  /// tracing was started from the StartTrace. In case tracing of the complete
-  /// process needs to be stopped the thread_id should be set to
-  /// LLDB_INVALID_THREAD_ID. In the other case that tracing on an individual
-  /// thread needs to be stopped a thread_id can be supplied.
-  virtual Status StopTrace(lldb::user_id_t uid, lldb::tid_t thread_id) {
-    return Status("Not implemented");
-  }
-
-  /// Deprecated
-  ///
-  /// Provides the trace data as raw bytes. A buffer needs to be supplied to
-  /// copy the trace data. The exact behavior of this API may vary across
-  /// trace technology, as some may support partial reading of the trace data
-  /// from a specified offset while some may not. The thread_id should be used
-  /// to select a particular thread for trace extraction.
-  virtual Status GetData(lldb::user_id_t uid, lldb::tid_t thread_id,
-                         llvm::MutableArrayRef<uint8_t> &buffer,
-                         size_t offset = 0) {
-    return Status("Not implemented");
-  }
-
-  /// Deprecated
-  ///
-  /// Similar API as above except for obtaining meta data
-  virtual Status GetMetaData(lldb::user_id_t uid, lldb::tid_t thread_id,
-                             llvm::MutableArrayRef<uint8_t> &buffer,
-                             size_t offset = 0) {
-    return Status("Not implemented");
-  }
-
 protected:
   friend class Trace;
   ///  Get the processor tracing type supported for this process.
   ///  Responses might be different depending on the architecture and
   ///  capabilities of the underlying OS.
   ///
   ///  \return
   ///     The supported trace type or an \a llvm::Error if tracing is

lldb/include/lldb/Target/Trace.h

 #include "lldb/Target/Thread.h"
 #include "lldb/Utility/ArchSpec.h"
 #include "lldb/Utility/TraceGDBRemotePackets.h"
 #include "lldb/Utility/UnimplementedError.h"
 #include "lldb/lldb-private.h"
 
 namespace lldb_private {
 
+class TraceInstruction {
+  bool IsError(); // true if this represents a decoding error
+
+  const char *GetErrorMessage(); // the decoding error message or nullptr
+
+  TraceInstructionType GetInstructionType(); // the instruction type enum for analysis
+
+  lldb::addr_t GetLoadAddress(); // the load address if not an error, or LLDB_INVALID_ADDRESS
+
+  lldb::addr_t GetJumpAddress(); // the target address for any call, return, jump, etc.
+                                 // or LLDB_INVALID_ADDRESS if it doesn't make sense or
+                                 // couldn't be determined
+}
+
 /// \class Trace Trace.h "lldb/Target/Trace.h"
 /// A plug-in interface definition class for trace information.
 ///
 /// Trace plug-ins allow processor trace information to be loaded into LLDB so
 /// that the data can be dumped, used for reverse and forward stepping to allow
 /// introspection into the reason your process crashed or found its way to its
 /// current state.
 ///
 /// Trace information can be loaded into a target without a process to allow
 /// introspection of the trace information during post mortem analysis, such as
 /// when loading core files.
 ///
 /// Processor trace information can also be fetched through the process
 /// interfaces during a live debug session if your process supports gathering
 /// this information.
 ///
 /// In order to support live tracing, the name of the plug-in should match the
 /// name of the tracing type returned by the gdb-remote packet
 /// \a jLLDBTraceSupported.
 class Trace : public PluginInterface,
               public std::enable_shared_from_this<Trace> {
 public:
-  enum class TraceDirection {
-    Forwards = 0,
-    Backwards,
-  };
-
   /// Dump the trace data that this plug-in has access to.
   ///
   /// This function will dump all of the trace data for all threads in a user
   /// readable format. Options for dumping can be added as this API is iterated
   /// on.
   ///
   /// \param[in] s
   ///     A stream object to dump the information to.
public:
   ///
   /// \param[in] end_position
   ///     The position of the last instruction to print.
   ///
   /// \param[in] raw
   ///     Dump only instruction addresses without disassembly nor symbol
   ///     information.
   void DumpTraceInstructions(Thread &thread, Stream &s, size_t count,
-                             size_t end_position, bool raw);
+                             int end_position, bool raw);
 
-  /// Run the provided callback on the instructions of the trace of the given
-  /// thread.
-  ///
-  /// The instructions will be traversed starting at the given \a position
-  /// sequentially until the callback returns \b false, in which case no more
-  /// instructions are inspected.
-  ///
-  /// The purpose of this method is to allow inspecting traced instructions
-  /// without exposing the internal representation of how they are stored on
-  /// memory.
-  ///
-  /// \param[in] thread
-  ///     The thread whose trace will be traversed.
-  ///
-  /// \param[in] position
-  ///     The instruction position to start iterating on.
-  ///
-  /// \param[in] direction
-  ///     If \b TraceDirection::Forwards, then then instructions will be
-  ///     traversed forwards chronologically, i.e. with incrementing indices. If
-  ///     \b TraceDirection::Backwards, the traversal is done backwards
-  ///     chronologically, i.e. with decrementing indices.
-  ///
-  /// \param[in] callback
-  ///     The callback to execute on each instruction. If it returns \b false,
-  ///     the iteration stops.
+  /// \copydoc \a SBTrace::TraverseInstructions
   virtual void TraverseInstructions(
-      Thread &thread, size_t position, TraceDirection direction,
-      std::function<bool(size_t index, llvm::Expected<lldb::addr_t> load_addr)>
+      Thread &thread, int start_position, lldb::TraceDirection direction,
+      std::function<bool(int index, llvm::Expected<lldb::addr_t> load_addr)>
           callback) = 0;
 
   /// Get the number of available instructions in the trace of the given thread.
   ///
   /// \param[in] thread
   ///     The thread whose trace will be inspected.
   ///
   /// \return
   ///     The total number of instructions in the trace, or \a llvm::None if the
   ///     thread is not being traced.
   virtual llvm::Optional<size_t> GetInstructionCount(Thread &thread) = 0;
 
   /// Check if a thread is currently traced by this object.
   ///
   /// \param[in] thread
   ///     The thread in question.
   ///
   /// \return
   ///     \b true if the thread is traced by this instance, \b false otherwise.
   virtual bool IsTraced(const Thread &thread) = 0;
 
+  /// Start tracing a live process.
+  ///
+  /// \param[in] configuration
+  ///     See \a SBTrace::StartProcess(const lldb::SBStructuredData &) for more information.
+  ///
+  /// \return
+  ///     \a llvm::Error::success if the operation was successful, or
+  ///     \a llvm::Error otherwise.
+  virtual llvm::Error StartProcess(StructuredData::ObjectSP configuration = StructuredData::ObjectSP()) = 0;
+
+  /// Start tracing live threads.
+  ///
+  /// \param[in] tids
+  ///     Threads to trace. This method tries to trace as many threads as possible.
+  ///
+  /// \param[in] configuration
+  ///     See \a SBTrace::StartThread(const lldb::SBThread &, const lldb::SBStructuredData &) for more information.
+  ///
+  /// \return
+  ///     \a llvm::Error::success if the operation was successful, or
+  ///     \a llvm::Error otherwise.
+  virtual llvm::Error StartThreads(const std::vector<lldb::tid_t> &tids, StructuredData::ObjectSP configuration = StructuredData::ObjectSP()) = 0;
+
   /// Stop tracing live threads.
   ///
   /// \param[in] tids
   ///     The threads to stop tracing on.
   ///
   /// \return
   ///     \a llvm::Error::success if the operation was successful, or
   ///     \a llvm::Error otherwise.

lldb/include/lldb/Utility/TraceGDBRemotePackets.h

 llvm::json::Value toJSON(const TraceSupportedResponse &packet);
 /// \}
 
 /// jLLDBTraceStart gdb-remote packet
 /// \{
 struct TraceStartRequest {
   /// Tracing technology name, e.g. intel-pt, arm-coresight.
   std::string type;
+
   /// If \a llvm::None, then this starts tracing the whole process. Otherwise,
   /// only tracing for the specified threads is enabled.
   llvm::Optional<std::vector<int64_t>> tids;
 
+  /// \return
+  ///     \b true if tids is empty, i.e. whole process tracing.
   bool IsProcessTracing() const;
 };
 
 bool fromJSON(const llvm::json::Value &value, TraceStartRequest &packet,
               llvm::json::Path path);
 
 llvm::json::Value toJSON(const TraceStartRequest &packet);
 /// \}

lldb/include/lldb/Utility/TraceOptions.h

-//===-- TraceOptions.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_TRACEOPTIONS_H
-#define LLDB_UTILITY_TRACEOPTIONS_H
-
-#include "lldb/lldb-defines.h"
-#include "lldb/lldb-enumerations.h"
-
-#include "lldb/Utility/StructuredData.h"
-
-namespace lldb_private {
-
-/// Deprecated
-class TraceOptions {
-public:
-  TraceOptions() : m_trace_params(new StructuredData::Dictionary()) {}
-
-  const StructuredData::DictionarySP &getTraceParams() const {
-    return m_trace_params;
-  }
-
-  lldb::TraceType getType() const { return m_type; }
-
-  uint64_t getTraceBufferSize() const { return m_trace_buffer_size; }
-
-  uint64_t getMetaDataBufferSize() const { return m_meta_data_buffer_size; }
-
-  void setTraceParams(const StructuredData::DictionarySP &dict_obj) {
-    m_trace_params = dict_obj;
-  }
-
-  void setType(lldb::TraceType type) { m_type = type; }
-
-  void setTraceBufferSize(uint64_t size) { m_trace_buffer_size = size; }
-
-  void setMetaDataBufferSize(uint64_t size) { m_meta_data_buffer_size = size; }
-
-  void setThreadID(lldb::tid_t thread_id) { m_thread_id = thread_id; }
-
-  lldb::tid_t getThreadID() const { return m_thread_id; }
-
-private:
-  lldb::TraceType m_type;
-  uint64_t m_trace_buffer_size;
-  uint64_t m_meta_data_buffer_size;
-  lldb::tid_t m_thread_id;
-
-  /// m_trace_params is meant to hold any custom parameters
-  /// apart from meta buffer size and trace size.
-  /// The interpretation of such parameters is left to
-  /// the lldb-server.
-  StructuredData::DictionarySP m_trace_params;
-};
-
-} // namespace lldb_private
-
-#endif // LLDB_UTILITY_TRACEOPTIONS_H

lldb/include/lldb/lldb-enumerations.h

enum BasicType {
   eBasicTypeLongDoubleComplex,
   eBasicTypeObjCID,
   eBasicTypeObjCClass,
   eBasicTypeObjCSel,
   eBasicTypeNullPtr,
   eBasicTypeOther
 };
 
+/// The direction for traversing instructions of the \a SBTrace::TraverseInstruction method.
+enum TraceDirection {
+  eTraceDirectionForwards = 0,
+  eTraceDirectionBackwards
+};
+
+/// Architecture-agnostic categorization of instructions. Useful for doing analysis on traces.
+enum TraceInstructionType {
+    /// The instruction is not recognized by LLLDB
+    eTraceInstructionUnknown = 0,
+    /// The instruction is something not listed below
+    eTraceInstructionOther,
+    /// The instruction is a near (function) call
+    eTraceInstructionCall,
+    /// The instruction is a near (function) return
+    eTraceInstructionReturn,
+    /// The instruction is a near unconditional jump
+    eTraceInstructionJump,
+    /// The instruction is a near conditional jump
+    eTraceInstructionCondJump,
+    /// The instruction is a call-like far transfer
+    /// e.g. SYSCALL, SYSENTER, or FAR CALL
+    eTraceInstructionFarCall,
+    /// The instruction is a return-like far transfer
+    /// e.g. SYSRET, SYSEXIT, IRET, or FAR RET
+    eTraceInstructionFarReturn,
+    /// The instruction is a jump-like far transfer
+    /// e.g. FAR JMP
+    eTraceInstructionFarJump,
+    /// The instruction is a PTWRITE or similar
+    eTraceInstructionTraceWrite,
+    /// The instruction is an indirect jump or a far transfer
+    eTraceInstructionIndirect
+};
+
 /// Deprecated
 enum TraceType {
   eTraceTypeNone = 0,
 
   /// Intel Processor Trace
   eTraceTypeProcessorTrace
 };
 

lldb/include/lldb/lldb-forward.h

 class ThreadPlanStepOverBreakpoint;
 class ThreadPlanStepRange;
 class ThreadPlanStepThrough;
 class ThreadPlanTracer;
 class ThreadSpec;
 class ThreadPostMortemTrace;
 class Trace;
 class TraceSessionFileParser;
-class TraceOptions;
 class Type;
 class TypeAndOrName;
 class TypeCategoryImpl;
 class TypeCategoryMap;
 class TypeEnumMemberImpl;
 class TypeEnumMemberListImpl;
 class TypeFilterImpl;
 class TypeFormatImpl;

 typedef std::weak_ptr<lldb_private::Thread> ThreadWP;
 typedef std::shared_ptr<lldb_private::ThreadCollection> ThreadCollectionSP;
 typedef std::shared_ptr<lldb_private::ThreadPlan> ThreadPlanSP;
 typedef std::shared_ptr<lldb_private::ThreadPostMortemTrace>
     ThreadPostMortemTraceSP;
 typedef std::weak_ptr<lldb_private::ThreadPlan> ThreadPlanWP;
 typedef std::shared_ptr<lldb_private::ThreadPlanTracer> ThreadPlanTracerSP;
 typedef std::shared_ptr<lldb_private::Trace> TraceSP;
-typedef std::shared_ptr<lldb_private::TraceOptions> TraceOptionsSP;
 typedef std::shared_ptr<lldb_private::Type> TypeSP;
 typedef std::weak_ptr<lldb_private::Type> TypeWP;
 typedef std::shared_ptr<lldb_private::TypeCategoryImpl> TypeCategoryImplSP;
 typedef std::shared_ptr<lldb_private::TypeImpl> TypeImplSP;
 typedef std::shared_ptr<lldb_private::TypeMemberFunctionImpl>
     TypeMemberFunctionImplSP;
 typedef std::shared_ptr<lldb_private::TypeEnumMemberImpl> TypeEnumMemberImplSP;
 typedef std::shared_ptr<lldb_private::TypeFilterImpl> TypeFilterImplSP;

lldb/packages/Python/lldbsuite/test/dotest.py

def setupSysPath():
 
     # Set up the LLDB_SRC environment variable, so that the tests can locate
     # the LLDB source code.
     os.environ["LLDB_SRC"] = lldbsuite.lldb_root
 
     pluginPath = os.path.join(scriptPath, 'plugins')
     toolsLLDBVSCode = os.path.join(scriptPath, 'tools', 'lldb-vscode')
     toolsLLDBServerPath = os.path.join(scriptPath, 'tools', 'lldb-server')
+    intelpt = os.path.join(scriptPath, 'tools', 'intelpt')
 
     # Insert script dir, plugin dir and lldb-server dir to the sys.path.
     sys.path.insert(0, pluginPath)
     # Adding test/tools/lldb-vscode to the path makes it easy to
     # "import lldb_vscode_testcase" from the VSCode tests
     sys.path.insert(0, toolsLLDBVSCode)
     # Adding test/tools/lldb-server to the path makes it easy
-    sys.path.insert(0, toolsLLDBServerPath)
     # to "import lldbgdbserverutils" from the lldb-server tests
+    sys.path.insert(0, toolsLLDBServerPath)
+    # Adding test/tools/intelpt to the path makes it easy
+    # to "import intelpt_testcase" from the lldb-server tests
+    sys.path.insert(0, intelpt)
 
     # This is the root of the lldb git/svn checkout
     # When this changes over to a package instead of a standalone script, this
     # will be `lldbsuite.lldb_root`
     lldbRootDirectory = lldbsuite.lldb_root
 
     # Some of the tests can invoke the 'lldb' command directly.
     # We'll try to locate the appropriate executable right here.

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

+
+from lldbsuite.test.lldbtest import *
+import os
+import time
+import json
+
+ADDRESS_REGEX = '0x[0-9a-fA-F]*'
+
+# Decorator that runs a test with both modes of USE_SB_API
+def testSBAPIAndCommands(func):
+    def wrapper(*args, **kwargs):
+        USE_SB_API = True
+        func(*args, **kwargs)
+        USE_SB_API = False
+        func(*args, **kwargs)
+    return wrapper
+
+class TraceIntelPTTestCaseBase(TestBase):
+
+    NO_DEBUG_INFO_TESTCASE = True
+
+    # If True, the trace test methods will use the SB API, otherwise they'll use raw commands.
+    USE_SB_API = False
+
+    def setUp(self):
+        TestBase.setUp(self)
+        if 'intel-pt' not in configuration.enabled_plugins:
+            self.skipTest("The intel-pt test plugin is not enabled")
+
+    def assertSBError(self, sberror, error=False):
+        if error:
+            self.assertTrue(sberror.Fail())
+        else:
+            self.assertSuccess(sberror)
+
+    def createConfiguration(self, threadBufferSize=None, processBufferSizeLimit=None):
+        obj = {}
+        if processBufferSizeLimit is not None:
+            obj["processBufferSizeLimit"] = processBufferSizeLimit
+        if threadBufferSize is not None:
+            obj["threadBufferSize"]  = threadBufferSize
+
+        configuration = lldb.SBStructuredData()
+        configuration.SetFromJSON(json.dumps(obj))
+        return configuration
+
+    def traceStartThread(self, thread=None, error=False, substrs=None, threadBufferSize=None):
+        if self.USE_SB_API:
+            sberror = lldb.SBError()
+            trace = self.target().GetTraceOrCreate(sberror)
+
+            thread = thread if thread is not None else self.thread()
+
+            # We do the following to test both APIs
+            if threadBufferSize is None:
+                self.assertSBError(trace.StartThread(thread), error)
+            else:
+                configuration = self.createConfiguration(threadBufferSize=threadBufferSize)
+                self.assertSBError(trace.StartThread(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)
+            self.expect(command, error=error, substrs=substrs)
+
+    def traceStartProcess(self, processBufferSizeLimit=None, error=False, substrs=None):
+        if self.USE_SB_API:
+            error = lldb.SBError()
+            trace = self.target().GetTraceOrCreate(error)
+
+            # We do the following to test both APIs
+            if processBufferSizeLimit is None:
+                self.assertSBError(trace.StartProcess(), error=error)
+            else:
+                configuration = self.createConfiguration(processBufferSizeLimit=processBufferSizeLimit)
+                self.assertSBError(trace.StartProcess(configuration), error=error)
+        else:
+            command = "process trace start"
+            if processBufferSizeLimit != None:
+                command += " -l " + str(processBufferSizeLimit)
+            self.expect(command, error=error, substrs=substrs)
+
+    def traceStopProcess(self):
+        if self.USE_SB_API:
+            self.assertSuccess(self.target().GetTrace().StopProcess())
+        else:
+            self.expect("process trace stop")
+
+    def traceStopThread(self, thread=None, error=False):
+        if self.USE_SB_API:
+            thread = thread if thread is not None else self.thread()
+            self.assertSBError(self.target().GetTrace().StopThread(thread), error)
+
+        else:
+            command = "thread trace stop"
+            if thread is not None:
+                command += " " + str(thread.GetIndexID())
+            self.expect(command, error=error)

lldb/source/API/SBProcess.cpp

size_t SBProcess::GetAsyncProfileData(char *dst, size_t dst_len) const {
 
   return bytes_read;
 }
 
 lldb::SBTrace SBProcess::StartTrace(SBTraceOptions &options,
                                     lldb::SBError &error) {
   LLDB_RECORD_METHOD(lldb::SBTrace, SBProcess, StartTrace,
                      (lldb::SBTraceOptions &, lldb::SBError &), options, error);
-
-  ProcessSP process_sp(GetSP());
-  error.Clear();
+  error.SetErrorString("deprecated");
   SBTrace trace_instance;
-  trace_instance.SetSP(process_sp);
-  lldb::user_id_t uid = LLDB_INVALID_UID;
-
-  if (!process_sp) {
-    error.SetErrorString("invalid process");
-  } else {
-    uid = process_sp->StartTrace(*(options.m_traceoptions_sp), error.ref());
-    trace_instance.SetTraceUID(uid);
-  }
   return LLDB_RECORD_RESULT(trace_instance);
 }
 
 void SBProcess::ReportEventState(const SBEvent &event, SBFile out) const {
   LLDB_RECORD_METHOD_CONST(void, SBProcess, ReportEventState,
                            (const SBEvent &, SBFile), event, out);
 
   return ReportEventState(event, out.m_opaque_sp);

lldb/source/API/SBReproducer.cpp

SBRegistry::SBRegistry() {
   RegisterMethods<SBSymbol>(R);
   RegisterMethods<SBSymbolContext>(R);
   RegisterMethods<SBSymbolContextList>(R);
   RegisterMethods<SBTarget>(R);
   RegisterMethods<SBThread>(R);
   RegisterMethods<SBThreadCollection>(R);
   RegisterMethods<SBThreadPlan>(R);
   RegisterMethods<SBTrace>(R);
-  RegisterMethods<SBTraceOptions>(R);
   RegisterMethods<SBType>(R);
   RegisterMethods<SBTypeCategory>(R);
   RegisterMethods<SBTypeEnumMember>(R);
   RegisterMethods<SBTypeFilter>(R);
   RegisterMethods<SBTypeFormat>(R);
   RegisterMethods<SBTypeNameSpecifier>(R);
   RegisterMethods<SBTypeSummary>(R);
   RegisterMethods<SBTypeSummaryOptions>(R);

lldb/source/API/SBStructuredData.cpp

lldb::SBError SBStructuredData::SetFromJSON(lldb::SBStream &stream) {
   StructuredData::ObjectSP json_obj = StructuredData::ParseJSON(json_str);
   m_impl_up->SetObjectSP(json_obj);
 
   if (!json_obj || json_obj->GetType() != eStructuredDataTypeDictionary)
     error.SetErrorString("Invalid Syntax");
   return LLDB_RECORD_RESULT(error);
 }
 
+lldb::SBError SBStructuredData::SetFromJSON(const char *json) {
+  LLDB_RECORD_METHOD(lldb::SBError, SBStructuredData, SetFromJSON,
+                     (const char *), json);
+
+  lldb::SBStream s;
+  s.Print(json);
+  return LLDB_RECORD_RESULT(SetFromJSON(s));
+}
+
+
 bool SBStructuredData::IsValid() const {
   LLDB_RECORD_METHOD_CONST_NO_ARGS(bool, SBStructuredData, IsValid);
   return this->operator bool();
 }
 SBStructuredData::operator bool() const {
   LLDB_RECORD_METHOD_CONST_NO_ARGS(bool, SBStructuredData, operator bool);
 
   return m_impl_up->IsValid();
template <> void RegisterMethods<SBStructuredData>(Registry &R) {
   LLDB_REGISTER_CONSTRUCTOR(SBStructuredData, (const lldb::EventSP &));
   LLDB_REGISTER_CONSTRUCTOR(SBStructuredData,
                             (lldb_private::StructuredDataImpl *));
   LLDB_REGISTER_METHOD(
       lldb::SBStructuredData &,
       SBStructuredData, operator=,(const lldb::SBStructuredData &));
   LLDB_REGISTER_METHOD(lldb::SBError, SBStructuredData, SetFromJSON,
                        (lldb::SBStream &));
+  LLDB_REGISTER_METHOD(lldb::SBError, SBStructuredData, SetFromJSON,
+                     (const char *));
   LLDB_REGISTER_METHOD_CONST(bool, SBStructuredData, IsValid, ());
   LLDB_REGISTER_METHOD_CONST(bool, SBStructuredData, operator bool, ());
   LLDB_REGISTER_METHOD(void, SBStructuredData, Clear, ());
   LLDB_REGISTER_METHOD_CONST(lldb::SBError, SBStructuredData, GetAsJSON,
                              (lldb::SBStream &));
   LLDB_REGISTER_METHOD_CONST(lldb::SBError, SBStructuredData, GetDescription,
                              (lldb::SBStream &));
   LLDB_REGISTER_METHOD_CONST(lldb::StructuredDataType, SBStructuredData,

lldb/source/API/SBTarget.cpp

 #include "lldb/API/SBModule.h"
 #include "lldb/API/SBModuleSpec.h"
 #include "lldb/API/SBProcess.h"
 #include "lldb/API/SBSourceManager.h"
 #include "lldb/API/SBStream.h"
 #include "lldb/API/SBStringList.h"
 #include "lldb/API/SBStructuredData.h"
 #include "lldb/API/SBSymbolContextList.h"
+#include "lldb/API/SBTrace.h"
 #include "lldb/Breakpoint/BreakpointID.h"
 #include "lldb/Breakpoint/BreakpointIDList.h"
 #include "lldb/Breakpoint/BreakpointList.h"
 #include "lldb/Breakpoint/BreakpointLocation.h"
 #include "lldb/Core/Address.h"
 #include "lldb/Core/AddressResolver.h"
 #include "lldb/Core/Debugger.h"
 #include "lldb/Core/Disassembler.h"
SBEnvironment SBTarget::GetEnvironment() {
 
   if (target_sp) {
     return LLDB_RECORD_RESULT(SBEnvironment(target_sp->GetEnvironment()));
   }
 
   return LLDB_RECORD_RESULT(SBEnvironment());
 }
 
+lldb::SBTrace SBTarget::GetTrace() {
+  LLDB_RECORD_METHOD_NO_ARGS(lldb::SBTrace, SBTarget, GetTrace);
+  TargetSP target_sp(GetSP());
+
+  if (target_sp)
+    return LLDB_RECORD_RESULT(SBTrace(target_sp->GetTrace()));
+
+  return LLDB_RECORD_RESULT(SBTrace());
+}
+
+lldb::SBTrace SBTarget::GetTraceOrCreate(lldb::SBError &error) {
+  LLDB_RECORD_METHOD(lldb::SBTrace, SBTarget, GetTraceOrCreate, (lldb::SBError &), error);
+  TargetSP target_sp(GetSP());
+  error.Clear();
+
+  if (target_sp) {
+    if (llvm::Expected<lldb::TraceSP &> trace_sp = target_sp->GetTraceOrCreate()) {
+      return LLDB_RECORD_RESULT(SBTrace(*trace_sp));
+    } else {
+      error.SetErrorString(llvm::toString(trace_sp.takeError()).c_str());
+    }
+  } else {
+    error.SetErrorString("missing target");
+  }
+  return LLDB_RECORD_RESULT(SBTrace());
+
+}
+
 namespace lldb_private {
 namespace repro {
 
 template <>
 void RegisterMethods<SBTarget>(Registry &R) {
   LLDB_REGISTER_CONSTRUCTOR(SBTarget, ());
   LLDB_REGISTER_CONSTRUCTOR(SBTarget, (const lldb::SBTarget &));
   LLDB_REGISTER_CONSTRUCTOR(SBTarget, (const lldb::TargetSP &));
LLDB_REGISTER_METHOD(lldb::SBInstructionList, SBTarget,
                        GetInstructionsWithFlavor,
                        (lldb::SBAddress, const char *, const void *, size_t));
   LLDB_REGISTER_METHOD(lldb::SBInstructionList, SBTarget, GetInstructions,
                        (lldb::addr_t, const void *, size_t));
   LLDB_REGISTER_METHOD(lldb::SBInstructionList, SBTarget,
                        GetInstructionsWithFlavor,
                        (lldb::addr_t, const char *, const void *, size_t));
   LLDB_REGISTER_METHOD(lldb::SBEnvironment, SBTarget, GetEnvironment, ());
+  LLDB_REGISTER_METHOD(lldb::SBTrace, SBTarget, GetTrace, ());
+  LLDB_REGISTER_METHOD(lldb::SBTrace, SBTarget, GetTraceOrCreate, (lldb::SBError &));
 }
 
 }
 }

lldb/source/API/SBTrace.cpp

 //===-- SBTrace.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 "SBReproducerPrivate.h"
 #include "lldb/Target/Process.h"
 
+#include "lldb/API/SBStructuredData.h"
+#include "lldb/API/SBThread.h"
 #include "lldb/API/SBTrace.h"
 #include "lldb/API/SBTraceOptions.h"
 
+#include "lldb/Core/StructuredDataImpl.h"
+
 #include <memory>
 
 using namespace lldb;
 using namespace lldb_private;
 
-class TraceImpl {
-public:
-  lldb::user_id_t uid;
-};
+SBTrace::SBTrace() {
+  LLDB_RECORD_CONSTRUCTOR_NO_ARGS(SBTrace);
+}
 
-lldb::ProcessSP SBTrace::GetSP() const { return m_opaque_wp.lock(); }
+SBTrace::SBTrace(const lldb::TraceSP &trace_sp): m_opaque_sp(trace_sp) {
+  LLDB_RECORD_CONSTRUCTOR(SBTrace, (const lldb::TraceSP &), trace_sp);
+}
 
 size_t SBTrace::GetTraceData(SBError &error, void *buf, size_t size,
                              size_t offset, lldb::tid_t thread_id) {
   LLDB_RECORD_DUMMY(size_t, SBTrace, GetTraceData,
                     (lldb::SBError &, void *, size_t, size_t, lldb::tid_t),
                     error, buf, size, offset, thread_id);
-
-  ProcessSP process_sp(GetSP());
-  llvm::MutableArrayRef<uint8_t> buffer(static_cast<uint8_t *>(buf), size);
-  error.Clear();
-
-  if (!process_sp) {
-    error.SetErrorString("invalid process");
-  } else {
-    error.SetError(
-        process_sp->GetData(GetTraceUID(), thread_id, buffer, offset));
-  }
-  return buffer.size();
+  error.SetErrorString("error: unimplemented");
+  return 0;
 }
 
-size_t SBTrace::GetMetaData(SBError &error, void *buf, size_t size,
-                            size_t offset, lldb::tid_t thread_id) {
-  LLDB_RECORD_DUMMY(size_t, SBTrace, GetMetaData,
-                    (lldb::SBError &, void *, size_t, size_t, lldb::tid_t),
-                    error, buf, size, offset, thread_id);
-
-  ProcessSP process_sp(GetSP());
-  llvm::MutableArrayRef<uint8_t> buffer(static_cast<uint8_t *>(buf), size);
-  error.Clear();
-
-  if (!process_sp) {
-    error.SetErrorString("invalid process");
-  } else {
-    error.SetError(
-        process_sp->GetMetaData(GetTraceUID(), thread_id, buffer, offset));
-  }
-  return buffer.size();
+SBError SBTrace::StartProcess() {
+  LLDB_RECORD_METHOD_NO_ARGS(SBError, SBTrace, StartProcess);
+  return LLDB_RECORD_RESULT(StartProcess(SBStructuredData()));
+}
+
+SBError SBTrace::StartProcess(const SBStructuredData &configuration) {
+  LLDB_RECORD_METHOD(SBError, SBTrace, StartProcess, (const SBStructuredData &), configuration);
+  SBError error;
+  if (!m_opaque_sp)
+    error.SetErrorString("error: invalid trace");
+  else if (llvm::Error err = m_opaque_sp->StartProcess(configuration.m_impl_up->GetObjectSP()))
+    error.SetErrorString(llvm::toString(std::move(err)).c_str());
+  return LLDB_RECORD_RESULT(error);
+}
+
+SBError SBTrace::StartThread(const SBThread &thread) {
+  LLDB_RECORD_METHOD(SBError, SBTrace, StartThread, (const SBThread &), thread);
+  return LLDB_RECORD_RESULT(StartThread(thread, SBStructuredData()));
+}
+
+SBError SBTrace::StartThread(const SBThread &thread, const SBStructuredData &configuration) {
+  LLDB_RECORD_METHOD(SBError, SBTrace, StartThread, (const SBThread &, const SBStructuredData &), thread, configuration);
+
+  SBError error;
+  if (!m_opaque_sp)
+    error.SetErrorString("error: invalid trace");
+  else if (llvm::Error err = m_opaque_sp->StartThreads({thread.GetThreadID()}, configuration.m_impl_up->GetObjectSP()))
+    error.SetErrorString(llvm::toString(std::move(err)).c_str());
+  return LLDB_RECORD_RESULT(error);
+}
+
+SBError SBTrace::StopProcess() {
+  LLDB_RECORD_METHOD_NO_ARGS(SBError, SBTrace, StopProcess);
+  SBError error;
+  if (!m_opaque_sp)
+    error.SetErrorString("error: invalid trace");
+  else if (llvm::Error err = m_opaque_sp->StopProcess())
+    error.SetErrorString(llvm::toString(std::move(err)).c_str());
+  return LLDB_RECORD_RESULT(error);
+}
+
+SBError SBTrace::StopThread(const SBThread &thread) {
+  LLDB_RECORD_METHOD(SBError, SBTrace, StopThread, (const SBThread &), thread);
+  SBError error;
+  if (!m_opaque_sp)
+    error.SetErrorString("error: invalid trace");
+  else if (llvm::Error err = m_opaque_sp->StopThreads({thread.GetThreadID()}))
+    error.SetErrorString(llvm::toString(std::move(err)).c_str());
+  return LLDB_RECORD_RESULT(error);
 }
 
 void SBTrace::StopTrace(SBError &error, lldb::tid_t thread_id) {
   LLDB_RECORD_METHOD(void, SBTrace, StopTrace, (lldb::SBError &, lldb::tid_t),
                      error, thread_id);
-
-  ProcessSP process_sp(GetSP());
   error.Clear();
-
-  if (!process_sp) {
-    error.SetErrorString("invalid process");
-    return;
-  }
-  error.SetError(process_sp->StopTrace(GetTraceUID(), thread_id));
+  if (thread_id == LLDB_INVALID_THREAD_ID)
+    error = StopProcess();
+  else
+    error.SetErrorString("error: unimplemented");
 }
 
-void SBTrace::GetTraceConfig(SBTraceOptions &options, SBError &error) {
-  error.SetErrorString("deprecated");
+bool SBTrace::IsValid() {
+  LLDB_RECORD_METHOD_NO_ARGS(bool, SBTrace, IsValid);
+  return LLDB_RECORD_RESULT(this->operator bool());
 }
 
-lldb::user_id_t SBTrace::GetTraceUID() {
-  LLDB_RECORD_METHOD_NO_ARGS(lldb::user_id_t, SBTrace, GetTraceUID);
-
-  if (m_trace_impl_sp)
-    return m_trace_impl_sp->uid;
-  return LLDB_INVALID_UID;
+SBTrace::operator bool() const {
+  LLDB_RECORD_METHOD_CONST_NO_ARGS(bool, SBTrace, operator bool);
+  return LLDB_RECORD_RESULT((bool)m_opaque_sp);
 }
 
-void SBTrace::SetTraceUID(lldb::user_id_t uid) {
-  if (m_trace_impl_sp)
-    m_trace_impl_sp->uid = uid;
+SBError SBTrace::TraverseInstructions(SBThread thread, int start_position, TraceDirection direction, std::function<bool(int index, lldb::addr_t load_address)> callback) {
+  SBError error;
+  if (!m_opaque_sp)
+    error.SetErrorString("error: invalid trace");
+  else if (!thread.IsValid())
+    error.SetErrorString("error: invalid thread");
+  else if (!m_opaque_sp->IsTraced(*thread.get()))
+    error.SetErrorString("error: thread not traced");
+  else{
+    m_opaque_sp->TraverseInstructions(*thread.get(), start_position, direction,
+    [&](int index, llvm::Expected<lldb::addr_t> load_addr) {
+      if (load_addr) {
+        return callback(index, *load_addr);
+      } else {
+        return callback(index, 0);
       }
+    });
+  } if (llvm::Error err = m_opaque_sp->StopThreads({thread.GetThreadID()}))
+    error.SetErrorString(llvm::toString(std::move(err)).c_str());
+  return error;
 
-SBTrace::SBTrace() {
-  LLDB_RECORD_CONSTRUCTOR_NO_ARGS(SBTrace);
-
-  m_trace_impl_sp = std::make_shared<TraceImpl>();
-  if (m_trace_impl_sp)
-    m_trace_impl_sp->uid = LLDB_INVALID_UID;
 }
 
-void SBTrace::SetSP(const ProcessSP &process_sp) { m_opaque_wp = process_sp; }
+/// Deprecated
+size_t SBTrace::GetMetaData(SBError &error, void *buf, size_t size,
+                            size_t offset, lldb::tid_t thread_id) {
+  error.SetErrorString("error: deprecated");
+  return 0;
+}
 
-bool SBTrace::IsValid() {
-  LLDB_RECORD_METHOD_NO_ARGS(bool, SBTrace, IsValid);
-  return this->operator bool();
+/// Deprecated
+void SBTrace::GetTraceConfig(SBTraceOptions &options, SBError &error) {
+  error.SetErrorString("error: deprecated");
 }
-SBTrace::operator bool() const {
-  LLDB_RECORD_METHOD_CONST_NO_ARGS(bool, SBTrace, operator bool);
 
-  if (!m_trace_impl_sp)
-    return false;
-  if (!GetSP())
-    return false;
-  return true;
+/// Deprecated
+lldb::user_id_t SBTrace::GetTraceUID() {
+  return LLDB_INVALID_UID;
 }
 
 namespace lldb_private {
 namespace repro {
 
 template <>
 void RegisterMethods<SBTrace>(Registry &R) {
+  LLDB_REGISTER_CONSTRUCTOR(SBTrace, ());
+  LLDB_REGISTER_CONSTRUCTOR(SBTrace, (const lldb::TraceSP &));
   LLDB_REGISTER_METHOD(void, SBTrace, StopTrace,
                        (lldb::SBError &, lldb::tid_t));
-  LLDB_REGISTER_METHOD(void, SBTrace, GetTraceConfig,
-                       (lldb::SBTraceOptions &, lldb::SBError &));
-  LLDB_REGISTER_METHOD(lldb::user_id_t, SBTrace, GetTraceUID, ());
-  LLDB_REGISTER_CONSTRUCTOR(SBTrace, ());
+  LLDB_REGISTER_METHOD(SBError, SBTrace, StartProcess, (const SBStructuredData &));
+  LLDB_REGISTER_METHOD(SBError, SBTrace, StartThread, (const SBThread &));
+  LLDB_REGISTER_METHOD(SBError, SBTrace, StartThread, (const SBThread &, const SBStructuredData &));
+  LLDB_REGISTER_METHOD(SBError, SBTrace, StopProcess, ());
+  LLDB_REGISTER_METHOD(SBError, SBTrace, StopThread, (const SBThread &));
   LLDB_REGISTER_METHOD(bool, SBTrace, IsValid, ());
   LLDB_REGISTER_METHOD_CONST(bool, SBTrace, operator bool, ());
 }
 
 }
 }

lldb/source/API/SBTraceOptions.cpp

 //===-- SBTraceOptions.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 "lldb/API/SBTraceOptions.h"
-#include "SBReproducerPrivate.h"
 #include "lldb/API/SBError.h"
 #include "lldb/API/SBStructuredData.h"
-#include "lldb/Core/StructuredDataImpl.h"
-#include "lldb/Utility/Log.h"
-#include "lldb/Utility/TraceOptions.h"
 
 #include <memory>
 
 using namespace lldb;
 using namespace lldb_private;
 
 SBTraceOptions::SBTraceOptions() {
-  LLDB_RECORD_CONSTRUCTOR_NO_ARGS(SBTraceOptions);
-
-  m_traceoptions_sp = std::make_shared<TraceOptions>();
 }
 
 lldb::TraceType SBTraceOptions::getType() const {
-  LLDB_RECORD_METHOD_CONST_NO_ARGS(lldb::TraceType, SBTraceOptions, getType);
-
-  if (m_traceoptions_sp)
-    return m_traceoptions_sp->getType();
   return lldb::TraceType::eTraceTypeNone;
 }
 
 uint64_t SBTraceOptions::getTraceBufferSize() const {
-  LLDB_RECORD_METHOD_CONST_NO_ARGS(uint64_t, SBTraceOptions,
-                                   getTraceBufferSize);
-
-  if (m_traceoptions_sp)
-    return m_traceoptions_sp->getTraceBufferSize();
   return 0;
 }
 
 lldb::SBStructuredData SBTraceOptions::getTraceParams(lldb::SBError &error) {
-  LLDB_RECORD_METHOD(lldb::SBStructuredData, SBTraceOptions, getTraceParams,
-                     (lldb::SBError &), error);
-
-  error.Clear();
-  const lldb_private::StructuredData::DictionarySP dict_obj =
-      m_traceoptions_sp->getTraceParams();
-  lldb::SBStructuredData structData;
-  if (dict_obj && structData.m_impl_up)
-    structData.m_impl_up->SetObjectSP(dict_obj->shared_from_this());
-  else
-    error.SetErrorString("Empty trace params");
-  return LLDB_RECORD_RESULT(structData);
+  error.SetErrorString("deprecated");
+  return lldb::SBStructuredData();
 }
 
 uint64_t SBTraceOptions::getMetaDataBufferSize() const {
-  LLDB_RECORD_METHOD_CONST_NO_ARGS(uint64_t, SBTraceOptions,
-                                   getMetaDataBufferSize);
-
-  if (m_traceoptions_sp)
-    return m_traceoptions_sp->getTraceBufferSize();
   return 0;
 }
 
 void SBTraceOptions::setTraceParams(lldb::SBStructuredData &params) {
-  LLDB_RECORD_METHOD(void, SBTraceOptions, setTraceParams,
-                     (lldb::SBStructuredData &), params);
-
-  if (m_traceoptions_sp && params.m_impl_up) {
-    StructuredData::ObjectSP obj_sp = params.m_impl_up->GetObjectSP();
-    if (obj_sp && obj_sp->GetAsDictionary() != nullptr)
-      m_traceoptions_sp->setTraceParams(
-          std::static_pointer_cast<StructuredData::Dictionary>(obj_sp));
-  }
   return;
 }
 
 void SBTraceOptions::setType(lldb::TraceType type) {
-  LLDB_RECORD_METHOD(void, SBTraceOptions, setType, (lldb::TraceType), type);
-
-  if (m_traceoptions_sp)
-    m_traceoptions_sp->setType(type);
 }
 
 void SBTraceOptions::setTraceBufferSize(uint64_t size) {
-  LLDB_RECORD_METHOD(void, SBTraceOptions, setTraceBufferSize, (uint64_t),
-                     size);
-
-  if (m_traceoptions_sp)
-    m_traceoptions_sp->setTraceBufferSize(size);
 }
 
 void SBTraceOptions::setMetaDataBufferSize(uint64_t size) {
-  LLDB_RECORD_METHOD(void, SBTraceOptions, setMetaDataBufferSize, (uint64_t),
-                     size);
-
-  if (m_traceoptions_sp)
-    m_traceoptions_sp->setMetaDataBufferSize(size);
 }
 
 bool SBTraceOptions::IsValid() {
-  LLDB_RECORD_METHOD_NO_ARGS(bool, SBTraceOptions, IsValid);
-  return this->operator bool();
+  return false;
 }
 SBTraceOptions::operator bool() const {
-  LLDB_RECORD_METHOD_CONST_NO_ARGS(bool, SBTraceOptions, operator bool);
-
-  if (m_traceoptions_sp)
-    return true;
   return false;
 }
 
 void SBTraceOptions::setThreadID(lldb::tid_t thread_id) {
-  LLDB_RECORD_METHOD(void, SBTraceOptions, setThreadID, (lldb::tid_t),
-                     thread_id);
-
-  if (m_traceoptions_sp)
-    m_traceoptions_sp->setThreadID(thread_id);
 }
 
 lldb::tid_t SBTraceOptions::getThreadID() {
-  LLDB_RECORD_METHOD_NO_ARGS(lldb::tid_t, SBTraceOptions, getThreadID);
-
-  if (m_traceoptions_sp)
-    return m_traceoptions_sp->getThreadID();
   return LLDB_INVALID_THREAD_ID;
 }
-
-namespace lldb_private {
-namespace repro {
-
-template <>
-void RegisterMethods<SBTraceOptions>(Registry &R) {
-  LLDB_REGISTER_CONSTRUCTOR(SBTraceOptions, ());
-  LLDB_REGISTER_METHOD_CONST(lldb::TraceType, SBTraceOptions, getType, ());
-  LLDB_REGISTER_METHOD_CONST(uint64_t, SBTraceOptions, getTraceBufferSize,
-                             ());
-  LLDB_REGISTER_METHOD(lldb::SBStructuredData, SBTraceOptions, getTraceParams,
-                       (lldb::SBError &));
-  LLDB_REGISTER_METHOD_CONST(uint64_t, SBTraceOptions, getMetaDataBufferSize,
-                             ());
-  LLDB_REGISTER_METHOD(void, SBTraceOptions, setTraceParams,
-                       (lldb::SBStructuredData &));
-  LLDB_REGISTER_METHOD(void, SBTraceOptions, setType, (lldb::TraceType));
-  LLDB_REGISTER_METHOD(void, SBTraceOptions, setTraceBufferSize, (uint64_t));
-  LLDB_REGISTER_METHOD(void, SBTraceOptions, setMetaDataBufferSize,
-                       (uint64_t));
-  LLDB_REGISTER_METHOD(bool, SBTraceOptions, IsValid, ());
-  LLDB_REGISTER_METHOD_CONST(bool, SBTraceOptions, operator bool, ());
-  LLDB_REGISTER_METHOD(void, SBTraceOptions, setThreadID, (lldb::tid_t));
-  LLDB_REGISTER_METHOD(lldb::tid_t, SBTraceOptions, getThreadID, ());
-}
-
-}
-}

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

 //===-- CommandObjectTraceStartIntelPT.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 "CommandObjectTraceStartIntelPT.h"
 
+#include "constants.h"
 #include "TraceIntelPT.h"
 #include "lldb/Host/OptionParser.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/Trace.h"
 
 using namespace lldb;
 using namespace lldb_private;
 using namespace lldb_private::trace_intel_pt;
Status CommandObjectThreadTraceStartIntelPT::CommandOptions::SetOptionValue(
   default:
     llvm_unreachable("Unimplemented option");
   }
   return error;
 }
 
 void CommandObjectThreadTraceStartIntelPT::CommandOptions::
     OptionParsingStarting(ExecutionContext *execution_context) {
-  m_thread_buffer_size = 4 * 1024; // 4KB
+  m_thread_buffer_size = kThreadBufferSize;
 }
 
 llvm::ArrayRef<OptionDefinition>
 CommandObjectThreadTraceStartIntelPT::CommandOptions::GetDefinitions() {
   return llvm::makeArrayRef(g_thread_trace_start_intel_pt_options);
 }
 
 bool CommandObjectThreadTraceStartIntelPT::DoExecuteOnThreads(
     Args &command, CommandReturnObject &result,
     const std::vector<lldb::tid_t> &tids) {
-  if (Error err = m_trace.Start(tids, m_options.m_thread_buffer_size))
+  if (Error err = m_trace.StartThreads(tids, m_options.m_thread_buffer_size))
     result.SetError(toString(std::move(err)));
   else
     result.SetStatus(eReturnStatusSuccessFinishResult);
 
   return result.Succeeded();
 }
 
 /// CommandObjectProcessTraceStartIntelPT
Status CommandObjectProcessTraceStartIntelPT::CommandOptions::SetOptionValue(
   default:
     llvm_unreachable("Unimplemented option");
   }
   return error;
 }
 
 void CommandObjectProcessTraceStartIntelPT::CommandOptions::
     OptionParsingStarting(ExecutionContext *execution_context) {
-  m_thread_buffer_size = 4 * 1024;               // 4KB
-  m_process_buffer_size_limit = 5 * 1024 * 1024; // 500MB
+  m_thread_buffer_size = kThreadBufferSize;
+  m_process_buffer_size_limit = kProcessBufferSizeLimit;
 }
 
 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,
+  if (Error err = m_trace.StartProcess(m_options.m_thread_buffer_size,
                                 m_options.m_process_buffer_size_limit))
     result.SetError(toString(std::move(err)));
   else
     result.SetStatus(eReturnStatusSuccessFinishResult);
 
   return result.Succeeded();
 }

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

public:
   GetProcessTraceStartCommand(CommandInterpreter &interpreter) override;
 
   lldb::CommandObjectSP
   GetThreadTraceStartCommand(CommandInterpreter &interpreter) override;
 
   llvm::StringRef GetSchema() override;
 
   void TraverseInstructions(
-      Thread &thread, size_t position, TraceDirection direction,
-      std::function<bool(size_t index, llvm::Expected<lldb::addr_t> load_addr)>
+      Thread &thread, int position, lldb::TraceDirection direction,
+      std::function<bool(int index, llvm::Expected<lldb::addr_t> load_addr)>
           callback) override;
 
   llvm::Optional<size_t> GetInstructionCount(Thread &thread) override;
 
   size_t GetCursorPosition(Thread &thread) override;
 
   void DoRefreshLiveProcessState(
       llvm::Expected<TraceGetStateResponse> state) override;
public:
   ///
   ///     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.
   ///
   /// \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 StartProcess(size_t thread_buffer_size, size_t total_buffer_size_limit);
 
-  /// Start tracing a live threads.
+  /// \copydoc Trace::StartProcess(const llvm::Optional<StructuredData &>)
+  llvm::Error StartProcess(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.
   ///
   /// \return
   ///     \a llvm::Error::success if the operation was successful, or
   ///     \a llvm::Error otherwise.
-  llvm::Error Start(const std::vector<lldb::tid_t> &tids,
+  llvm::Error StartThreads(const std::vector<lldb::tid_t> &tids,
                     size_t thread_buffer_size);
 
+  llvm::Error StartThreads(const std::vector<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);
 
   llvm::Expected<pt_cpu> GetCPUInfo();
 
 private:
   friend class TraceIntelPTSessionFileParser;
 

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

 //===-- TraceIntelPT.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 "TraceIntelPT.h"
 
+#include "constants.h"
 #include "CommandObjectTraceStartIntelPT.h"
 #include "TraceIntelPTSessionFileParser.h"
 #include "lldb/Core/PluginManager.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/Target.h"
 #include "lldb/Target/ThreadPostMortemTrace.h"
 
 using namespace lldb;

 size_t TraceIntelPT::GetCursorPosition(Thread &thread) {
   const DecodedThread *decoded_thread = Decode(thread);
   if (!decoded_thread)
     return 0;
   return decoded_thread->GetCursorPosition();
 }
 
 void TraceIntelPT::TraverseInstructions(
-    Thread &thread, size_t position, TraceDirection direction,
-    std::function<bool(size_t index, Expected<lldb::addr_t> load_addr)>
+    Thread &thread, int position, TraceDirection direction,
+    std::function<bool(int index, Expected<lldb::addr_t> load_addr)>
         callback) {
   const DecodedThread *decoded_thread = Decode(thread);
   if (!decoded_thread)
     return;
 
   ArrayRef<IntelPTInstruction> instructions = decoded_thread->GetInstructions();
 
-  ssize_t delta = direction == TraceDirection::Forwards ? 1 : -1;
-  for (ssize_t i = position; i < (ssize_t)instructions.size() && i >= 0;
-       i += delta)
-    if (!callback(i, instructions[i].GetLoadAddress()))
+  int size = instructions.size();
+  int delta = direction == eTraceDirectionForwards ? 1 : -1;
+
+  for (int i = position < 0 ? size + position : position; i < size && i >= 0; i += delta, position += delta) {
+    if (!callback(position, instructions[i].GetLoadAddress()))
       break;
   }
+}
 
 Optional<size_t> TraceIntelPT::GetInstructionCount(Thread &thread) {
   if (const DecodedThread *decoded_thread = Decode(thread))
     return decoded_thread->GetInstructions().size();
   else
     return None;
 }
 
for (const TraceThreadState &thread_state : state->tracedThreads) {
     Thread &thread =
         *m_live_process->GetThreadList().FindThreadByID(thread_state.tid);
     m_thread_decoders.emplace(
         &thread, std::make_unique<LiveThreadDecoder>(thread, *this));
   }
 }
 
 bool TraceIntelPT::IsTraced(const Thread &thread) {
+  RefreshLiveProcessState();
   return m_thread_decoders.count(&thread);
 }
 
-Error TraceIntelPT::Start(size_t thread_buffer_size,
+Error TraceIntelPT::StartProcess(size_t thread_buffer_size,
                           size_t total_buffer_size_limit) {
   TraceIntelPTStartRequest request;
   request.threadBufferSize = thread_buffer_size;
   request.processBufferSizeLimit = total_buffer_size_limit;
   request.type = GetPluginName().AsCString();
   return Trace::Start(toJSON(request));
 }
 
-llvm::Error TraceIntelPT::Start(const std::vector<lldb::tid_t> &tids,
+Error TraceIntelPT::StartProcess(StructuredData::ObjectSP configuration) {
+  size_t thread_buffer_size = kThreadBufferSize;
+  size_t process_buffer_size_limit = kProcessBufferSizeLimit;
+
+  if (configuration) {
+    if (StructuredData::Dictionary *dict = configuration->GetAsDictionary()) {
+      dict->GetValueForKeyAsInteger("threadBufferSize", thread_buffer_size);
+      dict->GetValueForKeyAsInteger("processBufferSizeLimit", process_buffer_size_limit);
+    } else {
+      return createStringError(inconvertibleErrorCode(), "configuration object is not a dictionary");
+    }
+  }
+
+  return StartProcess(thread_buffer_size, process_buffer_size_limit);
+}
+
+Error TraceIntelPT::StartThreads(const std::vector<lldb::tid_t> &tids,
                                 size_t thread_buffer_size) {
   TraceIntelPTStartRequest request;
   request.threadBufferSize = thread_buffer_size;
   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::StartThreads(const std::vector<lldb::tid_t> &tids, StructuredData::ObjectSP configuration) {
+  size_t thread_buffer_size = kThreadBufferSize;
+
+  if (configuration) {
+    if (StructuredData::Dictionary *dict = configuration->GetAsDictionary()) {
+      dict->GetValueForKeyAsInteger("threadBufferSize", thread_buffer_size);
+    } else {
+      return createStringError(inconvertibleErrorCode(), "configuration object is not a dictionary");
+    }
+  }
+
+  return StartThreads(tids, thread_buffer_size);
+}
+
 Expected<std::vector<uint8_t>>
 TraceIntelPT::GetLiveThreadBuffer(lldb::tid_t tid) {
   return Trace::GetLiveThreadBinaryData(tid, "threadTraceBuffer");
 }

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

Desc<"Trace size in bytes per thread. It must be a power of 2 greater "
          "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 \"tracing\" "
-         "reason, so that the user can retrace the process if needed.">;
+         "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.">;
 }

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

 //===-- TraceIntelPTSessionFileParser.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 "TraceIntelPTSessionFileParser.h"
 
 #include "lldb/Core/Debugger.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/Target.h"
 #include "lldb/Target/ThreadList.h"
 #include "lldb/Target/ThreadPostMortemTrace.h"
-#include "lldb/Utility/TraceOptions.h"
 
 using namespace lldb;
 using namespace lldb_private;
 using namespace lldb_private::trace_intel_pt;
 using namespace llvm;
 
 StringRef TraceIntelPTSessionFileParser::GetSchema() {
   static std::string schema;

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

+//===-- DecodedThread.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
+
+namespace lldb_private {
+namespace trace_intel_pt {
+
+const size_t kThreadBufferSize = 4 * 1024;               // 4KB
+const size_t kProcessBufferSizeLimit = 5 * 1024 * 1024; // 500MB
+
+} // namespace trace_intel_pt
+} // namespace lldb_private
+
+#endif // LLDB_SOURCE_PLUGINS_TRACE_INTEL_PT_CONSTANTS_H

lldb/source/Target/Trace.cpp

 /// \param[in] symbol_scope
 ///     If not \b 0, then the \a InstructionSymbolInfo will have its
 ///     SymbolContext calculated up to that level.
 ///
 /// \param[in] include_disassembler
 ///     If \b true, then the \a InstructionSymbolInfo will have the
 ///     \a disassembler and \a instruction objects calculated.
 static void TraverseInstructionsWithSymbolInfo(
-    Trace &trace, Thread &thread, size_t position,
-    Trace::TraceDirection direction, SymbolContextItem symbol_scope,
+    Trace &trace, Thread &thread, int position,
+    TraceDirection direction, SymbolContextItem symbol_scope,
     bool include_disassembler,
-    std::function<bool(size_t index, Expected<InstructionSymbolInfo> insn)>
+    std::function<bool(int index, Expected<InstructionSymbolInfo> insn)>
         callback) {
   InstructionSymbolInfo prev_insn;
 
   Target &target = thread.GetProcess()->GetTarget();
   ExecutionContext exe_ctx;
   target.CalculateExecutionContext(exe_ctx);
   const ArchSpec &arch = target.GetArchitecture();
 
static void DumpInstructionDisassembly(Stream &s, InstructionSymbolInfo &insn) {
   insn.instruction->Dump(&s, /*show_address*/ false, /*show_bytes*/ false,
                          /*max_opcode_byte_size*/ 0, &insn.exe_ctx, &insn.sc,
                          /*prev_sym_ctx*/ nullptr,
                          /*disassembly_addr_format*/ nullptr,
                          /*max_address_text_size*/ 0);
 }
 
 void Trace::DumpTraceInstructions(Thread &thread, Stream &s, size_t count,
-                                  size_t end_position, bool raw) {
+                                  int end_position, bool raw) {
   Optional<size_t> instructions_count = GetInstructionCount(thread);
   if (!instructions_count) {
     s.Printf("thread #%u: tid = %" PRIu64 ", not traced\n", thread.GetIndexID(),
              thread.GetID());
     return;
   }
 
   s.Printf("thread #%u: tid = %" PRIu64 ", total instructions = %zu\n",
            thread.GetIndexID(), thread.GetID(), *instructions_count);
 
-  if (count == 0 || end_position >= *instructions_count)
+  if (count == 0 || end_position >= (int)*instructions_count)
     return;
 
   int digits_count = GetNumberOfDigits(end_position);
-  size_t start_position =
-      end_position + 1 < count ? 0 : end_position + 1 - count;
+  int start_position =
+      end_position + 1 < (int)count ? 0 : end_position + 1 - count;
   auto printInstructionIndex = [&](size_t index) {
     s.Printf("    [%*zu] ", digits_count, index);
   };
 
   bool was_prev_instruction_an_error = false;
   Optional<InstructionSymbolInfo> prev_insn;
 
   TraverseInstructionsWithSymbolInfo(
-      *this, thread, start_position, TraceDirection::Forwards,
+      *this, thread, start_position, eTraceDirectionForwards,
       eSymbolContextEverything, /*disassembler*/ true,
-      [&](size_t index, Expected<InstructionSymbolInfo> insn) -> bool {
+      [&](int index, Expected<InstructionSymbolInfo> insn) -> bool {
         if (!insn) {
           printInstructionIndex(index);
           s << toString(insn.takeError());
 
           prev_insn = None;
           was_prev_instruction_an_error = true;
         } else {
           if (was_prev_instruction_an_error)

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

 import lldb
+from intelpt_testcase import *
 from lldbsuite.test.lldbtest import *
 from lldbsuite.test import lldbutil
 from lldbsuite.test.decorators import *
 
-ADDRESS_REGEX = '0x[0-9a-fA-F]*'
-
-class TestTraceStartStop(TestBase):
+class TestTraceStartStop(TraceIntelPTTestCaseBase):
 
     mydir = TestBase.compute_mydir(__file__)
-    NO_DEBUG_INFO_TESTCASE = True
-
-    def setUp(self):
-        TestBase.setUp(self)
-        if 'intel-pt' not in configuration.enabled_plugins:
-            self.skipTest("The intel-pt test plugin is not enabled")
 
     def expectGenericHelpMessageForStartCommand(self):
         self.expect("help thread trace start",
             substrs=["Syntax: thread trace start [<trace-options>]"])
 
+    @testSBAPIAndCommands
     def testStartStopSessionFileThreads(self):
         # it should fail for processes from json session files
         self.expect("trace load -v " + os.path.join(self.getSourceDir(), "intelpt-trace", "trace.json"))
-        self.expect("thread trace start", error=True,
-            substrs=["error: Process must be alive"])
 
         # the help command should be the generic one, as it's not a live process
         self.expectGenericHelpMessageForStartCommand()
 
-        self.expect("thread trace stop", error=True)
+        self.traceStartThread(error=True)
 
-    def testStartWithNoProcess(self):
-        self.expect("thread trace start", error=True, 
-            substrs=["error: Process not available."])
+        self.traceStopThread(error=True)
 
+    @testSBAPIAndCommands
+    def testStartWithNoProcess(self):
+        self.traceStartThread(error=True)
 
+    @testSBAPIAndCommands
     def testStartSessionWithWrongSize(self):
         self.expect("file " + os.path.join(self.getSourceDir(), "intelpt-trace", "a.out"))
         self.expect("b main")
         self.expect("r")
-        self.expect("thread trace start -s 2000", error=True, 
+
+        self.traceStartThread(
+            error=True, threadBufferSize=2000,
             substrs=["The trace buffer size must be a power of 2", "It was 2000"])
-        self.expect("thread trace start -s 5000", error=True,
+
+        self.traceStartThread(
+            error=True, threadBufferSize=5000,
             substrs=["The trace buffer size must be a power of 2", "It was 5000"])
-        self.expect("thread trace start -s 0", error=True,
+
+        self.traceStartThread(
+            error=True, threadBufferSize=0,
             substrs=["The trace buffer size must be a power of 2", "It was 0"])
-        self.expect("thread trace start -s 1048576")
-        
+        self.traceStartThread(threadBufferSize=1048576)
 
     @skipIf(oslist=no_match(['linux']), archs=no_match(['i386', 'x86_64']))
     def testStartStopLiveThreads(self):
         # The help command should be the generic one if there's no process running
         self.expectGenericHelpMessageForStartCommand()
 
         self.expect("thread trace start", error=True,
             substrs=["error: Process not available"])
def testStartStopLiveThreads(self):
 
         # the help command should be the intel-pt one now
         self.expect("help thread trace start",
             substrs=["Start tracing one or more threads with intel-pt.",
                      "Syntax: thread trace start [<thread-index> <thread-index> ...] [<intel-pt-options>]"])
 
         # We start tracing with a small buffer size
         self.expect("thread trace start 1 --size 4096")
-        
         # We fail if we try to trace again
-        self.expect("thread trace start", error=True, 
+        self.expect("thread trace start", error=True,
             substrs=["error: Thread ", "already traced"])
 
         # We can reconstruct the single instruction executed in the first line
         self.expect("n")
-        self.expect("thread trace dump instructions", 
+        self.expect("thread trace dump instructions",
             patterns=[f'''thread #1: tid = .*, total instructions = 1
   a.out`main \+ 4 at main.cpp:2
     \[0\] {ADDRESS_REGEX}    movl'''])
 
         # We can reconstruct the instructions up to the second line
         self.expect("n")
-        self.expect("thread trace dump instructions", 
+        self.expect("thread trace dump instructions",
             patterns=[f'''thread #1: tid = .*, total instructions = 5
   a.out`main \+ 4 at main.cpp:2
     \[0\] {ADDRESS_REGEX}    movl .*
   a.out`main \+ 11 at main.cpp:4
     \[1\] {ADDRESS_REGEX}    movl .*
     \[2\] {ADDRESS_REGEX}    jmp  .* ; <\+28> at main.cpp:4
     \[3\] {ADDRESS_REGEX}    cmpl .*
     \[4\] {ADDRESS_REGEX}    jle  .* ; <\+20> at main.cpp:5'''])
 
         # We stop tracing
         self.expect("thread trace stop")
 
         # We can't stop twice
         self.expect("thread trace stop", error=True,
             substrs=["error: Thread ", "not currently traced"])
 
         # We trace again from scratch, this time letting LLDB to pick the current
         # thread
         self.expect("thread trace start")
         self.expect("n")
-        self.expect("thread trace dump instructions", 
+        self.expect("thread trace dump instructions",
             patterns=[f'''thread #1: tid = .*, total instructions = 1
   a.out`main \+ 20 at main.cpp:5
     \[0\] {ADDRESS_REGEX}    xorl'''])
 
         self.expect("c")
         # Now the process has finished, so the commands should fail
         self.expect("thread trace start", error=True,
             substrs=["error: Process must be launched"])
 
         self.expect("thread trace stop", error=True,
             substrs=["error: Process must be launched"])

lldb/test/API/commands/trace/multiple-threads/TestTraceStartStopMultipleThreads.py

 import lldb
+from intelpt_testcase import *
 from lldbsuite.test.lldbtest import *
 from lldbsuite.test import lldbutil
 from lldbsuite.test.decorators import *
 
-ADDRESS_REGEX = '0x[0-9a-fA-F]*'
-
-class TestTraceStartStopMultipleThreads(TestBase):
+class TestTraceStartStopMultipleThreads(TraceIntelPTTestCaseBase):
 
     mydir = TestBase.compute_mydir(__file__)
-    NO_DEBUG_INFO_TESTCASE = True
-
-    def setUp(self):
-        TestBase.setUp(self)
-        if 'intel-pt' not in configuration.enabled_plugins:
-            self.skipTest("The intel-pt test plugin is not enabled")
 
     @skipIf(oslist=no_match(['linux']), archs=no_match(['i386', 'x86_64']))
+    @testSBAPIAndCommands
     def testStartMultipleLiveThreads(self):
         self.build()
         exe = self.getBuildArtifact("a.out")
-        target = self.dbg.CreateTarget(exe)
+
+        self.dbg.CreateTarget(exe)
 
         self.expect("b main")
         self.expect("b 6")
         self.expect("b 11")
 
         self.expect("r")
-        self.expect("proce trace start")
+        self.traceStartProcess()
 
-
-        # We'll see here the first thread
         self.expect("continue")
         self.expect("thread trace dump instructions", substrs=['main.cpp:9'])
-        
         # We'll see here the second thread
         self.expect("continue")
         self.expect("thread trace dump instructions", substrs=['main.cpp:4'])
 
     @skipIf(oslist=no_match(['linux']), archs=no_match(['i386', 'x86_64']))
+    @testSBAPIAndCommands
     def testStartMultipleLiveThreadsWithStops(self):
         self.build()
         exe = self.getBuildArtifact("a.out")
-        target = self.dbg.CreateTarget(exe)
+
+        self.dbg.CreateTarget(exe)
 
         self.expect("b main")
         self.expect("b 6")
         self.expect("b 11")
 
         self.expect("r")
-        self.expect("process trace start")
-
+        self.traceStartProcess()
 
         # We'll see here the first thread
         self.expect("continue")
 
         # We are in thread 2
         self.expect("thread trace dump instructions", substrs=['main.cpp:9'])
         self.expect("thread trace dump instructions 2", substrs=['main.cpp:9'])
 
         # We stop tracing it
         self.expect("thread trace stop 2")
 
         # The trace is still in memory
         self.expect("thread trace dump instructions 2", substrs=['main.cpp:9'])
-        
         # We'll stop at the next breakpoint, thread 2 will be still alive, but not traced. Thread 3 will be traced
         self.expect("continue")
         self.expect("thread trace dump instructions", substrs=['main.cpp:4'])
         self.expect("thread trace dump instructions 3", substrs=['main.cpp:4'])
 
         self.expect("thread trace dump instructions 2", substrs=['not traced'])
 
     @skipIf(oslist=no_match(['linux']), archs=no_match(['i386', 'x86_64']))
+    @testSBAPIAndCommands
     def testStartMultipleLiveThreadsWithStops(self):
         self.build()
         exe = self.getBuildArtifact("a.out")
-        target = self.dbg.CreateTarget(exe)
+        self.dbg.CreateTarget(exe)
 
         self.expect("b main")
         self.expect("b 6")
         self.expect("b 11")
 
         self.expect("r")
-        self.expect("process trace start")
+
+        self.traceStartProcess()
 
         # We'll see here the first thread
         self.expect("continue")
 
         # We are in thread 2
         self.expect("thread trace dump instructions", substrs=['main.cpp:9'])
         self.expect("thread trace dump instructions 2", substrs=['main.cpp:9'])
 
         # We stop tracing all
         self.expect("thread trace stop all")
 
         # The trace is still in memory
         self.expect("thread trace dump instructions 2", substrs=['main.cpp:9'])
-        
         # We'll stop at the next breakpoint in thread 3, thread 2 and 3 will be alive, but only 3 traced.
         self.expect("continue")
         self.expect("thread trace dump instructions", substrs=['main.cpp:4'])
         self.expect("thread trace dump instructions 3", substrs=['main.cpp:4'])
         self.expect("thread trace dump instructions 1", substrs=['not traced'])
         self.expect("thread trace dump instructions 2", substrs=['not traced'])
 
     @skipIf(oslist=no_match(['linux']), archs=no_match(['i386', 'x86_64']))
def testStartMultipleLiveThreadsWithThreadStartAll(self):
 
         self.expect("thread trace dump instructions 2", substrs=['main.cpp:11'])
 
         # We stop tracing all
         self.runCmd("thread trace stop all")
 
         # The trace is still in memory
         self.expect("thread trace dump instructions 2", substrs=['main.cpp:11'])
-        
         # We'll stop at the next breakpoint in thread 3, and nothing should be traced
         self.expect("continue")
         self.expect("thread trace dump instructions 3", substrs=['not traced'])
         self.expect("thread trace dump instructions 1", substrs=['not traced'])
         self.expect("thread trace dump instructions 2", substrs=['not traced'])
 
     @skipIf(oslist=no_match(['linux']), archs=no_match(['i386', 'x86_64']))
+    @testSBAPIAndCommands
     def testStartMultipleLiveThreadsWithSmallTotalLimit(self):
         self.build()
         exe = self.getBuildArtifact("a.out")
-        target = self.dbg.CreateTarget(exe)
+
+        self.dbg.CreateTarget(exe)
 
         self.expect("b main")
         self.expect("r")
+
         # trace the entire process with enough total size for 1 thread trace
-        self.expect("process trace start -l 5000")
+        self.traceStartProcess(processBufferSizeLimit=5000)
+
         # we get the stop event when trace 2 appears and can't be traced
         self.expect("c", substrs=['Thread', "can't be traced"])
         # we get the stop event when trace 3 appears and can't be traced
         self.expect("c", substrs=['Thread', "can't be traced"])
+
+        self.traceStopProcess()

lldb/unittests/CMakeLists.txt

 add_subdirectory(Platform)
 add_subdirectory(Process)
 add_subdirectory(ScriptInterpreter)
 add_subdirectory(Signals)
 add_subdirectory(Symbol)
 add_subdirectory(SymbolFile)
 add_subdirectory(Target)
 add_subdirectory(tools)
+add_subdirectory(Trace)
 add_subdirectory(UnwindAssembly)
 add_subdirectory(Utility)
 add_subdirectory(Thread)
 
 if(LLDB_CAN_USE_DEBUGSERVER AND LLDB_TOOL_DEBUGSERVER_BUILD AND NOT LLDB_USE_SYSTEM_DEBUGSERVER)
   add_subdirectory(debugserver)
 endif()

lldb/unittests/Process/gdb-remote/GDBRemoteCommunicationClientTest.cpp

 //===-- GDBRemoteCommunicationClientTest.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 "Plugins/Process/gdb-remote/GDBRemoteCommunicationClient.h"
 #include "GDBRemoteTestUtils.h"
 #include "lldb/Core/ModuleSpec.h"
 #include "lldb/Host/XML.h"
 #include "lldb/Target/MemoryRegionInfo.h"
 #include "lldb/Utility/DataBuffer.h"
 #include "lldb/Utility/StructuredData.h"
-#include "lldb/Utility/TraceOptions.h"
 #include "lldb/lldb-enumerations.h"
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/Testing/Support/Error.h"
 #include "gmock/gmock.h"
 #include <future>
 
 using namespace lldb_private::process_gdb_remote;
 using namespace lldb_private;

lldb/unittests/Trace/CMakeLists.txt

+set(ALL_TRACE_TEST_EXECUTABLES)
+
+function(add_trace_test_executable test_name)
+  set(EXCLUDE_FROM_ALL ON)
+  add_llvm_executable(${test_name} NO_INSTALL_RPATH ${ARGN})
+  set(outdir ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR})
+  set_output_directory(${test_name} BINARY_DIR ${outdir} LIBRARY_DIR ${outdir})
+  list(APPEND ALL_TRACE_TEST_EXECUTABLES ${test_name})
+  set(ALL_TRACE_TEST_EXECUTABLES ${ALL_TRACE_TEST_EXECUTABLES} PARENT_SCOPE)
+  set_target_properties(${test_name} PROPERTIES FOLDER "lldb tests")
+endfunction()
+
+add_trace_test_executable(simple executables/simple.cpp)
+
+add_definitions(
+  -DLLDB_TRACE_TEST_EXECUTABLE_PATH="${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}"
+  -DLLDB_TRACE_TEST_EXECUTABLE_SUFFIX="${CMAKE_EXECUTABLE_SUFFIX}"
+  )
+
+add_subdirectory(tests)

lldb/unittests/Trace/executables/simple.cpp

+#include <cstdlib>
+
+int bar() {
+    int x = 1;
+    x++;
+    return x;
+}
+
+int foo() {
+    int x = bar();
+    x++;
+    return x;
+}
+
+int main() {
+    int x = foo();
+    exit(x);
+}

lldb/unittests/Trace/tests/CMakeLists.txt

+add_lldb_unittest(TraceTests
+  SBTraceTest.cpp
+
+  LINK_LIBS
+    liblldb
+  )
+
+add_dependencies(TraceTests ${ALL_TRACE_TEST_EXECUTABLES})
+
+
+if(Python3_RPATH)
+  set_property(TARGET APITests APPEND PROPERTY BUILD_RPATH "${Python3_RPATH}")
+endif()

lldb/unittests/Trace/tests/SBTraceTest.cpp

+//===-- SBTraceTest.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 "gtest/gtest.h"
+
+#include "lldb/API/SBCommandReturnObject.h"
+#include "lldb/API/SBCommandInterpreter.h"
+#include "lldb/API/SBDebugger.h"
+#include "lldb/API/SBLaunchInfo.h"
+#include "lldb/API/SBProcess.h"
+#include "lldb/API/SBTarget.h"
+#include "lldb/API/SBThread.h"
+#include "lldb/API/SBTrace.h"
+#include "llvm/Support/Path.h"
+
+#include <cstring>
+#include <string>
+
+using namespace lldb;
+
+static std::string getTestExecutablePath(llvm::StringRef name) {
+  llvm::SmallString<64> path(LLDB_TRACE_TEST_EXECUTABLE_PATH);
+  llvm::sys::path::append(path, name + LLDB_TRACE_TEST_EXECUTABLE_SUFFIX);
+  return std::string(path.str());
+}
+
+class SBTraceTest : public testing::Test {
+protected:
+  void SetUp() override {
+    SBDebugger::Initialize();
+    m_dbg = SBDebugger::Create(/*load init files*/ false);
+  }
+
+  SBDebugger m_dbg;
+};
+
+TEST_F(SBTraceTest, IterateThroughInstructions) {
+  m_dbg.SetAsync(false);
+
+  SBTarget target = m_dbg.CreateTarget(getTestExecutablePath("simple").c_str());
+  SBLaunchInfo launch_info = target.GetLaunchInfo();
+  launch_info.SetLaunchFlags(lldb::eLaunchFlagDebug | lldb::eLaunchFlagStopAtEntry);
+
+  SBError error;
+  target.Launch(launch_info, error);
+
+  EXPECT_TRUE(error.Success());
+
+  SBTrace trace = target.GetTraceOrCreate(error);
+
+  EXPECT_TRUE(trace.IsValid());
+
+  EXPECT_TRUE(trace.StartProcess().Success());
+
+  target.BreakpointCreateByName("exit");
+
+  SBProcess process = target.GetProcess();
+  process.Continue();
+
+  // we are stopped at exit, so we can now query the trace
+  int reps = 0;
+  error = trace.TraverseInstructions(process.GetSelectedThread(), -1, eTraceDirectionBackwards, [&](int index, lldb::addr_t address) {
+    printf("%d %d\n", index, (int)address);
+    reps++;
+    return reps < 5;
+  });
+  EXPECT_TRUE(error.Success());
+}