Initial implementation of SB APIs for Tracing support.

[ravitheja]

Summary

This patch introduces new SB APIs for tracing support
inside LLDB. The idea is to gather trace data from
LLDB and provide it through this APIs to external
tools integrating with LLDB. These tools will be
responsible for interpreting and presenting the
trace data to their users.

The patch implements the following new SB APIs ->
-> StartTrace - starts tracing with given parameters
-> StopTrace - stops tracing.
-> GetTraceData - read the trace data .
-> GetMetaData - read the meta data assosciated with the trace.
-> GetTraceConfig - read the trace configuration

Tracing is associated with a user_id that is returned
by the StartTrace API and this id needs to be used
for accessing the trace data and also Stopping
the trace. The user_id itself may map to tracing
the complete process or just an individual thread.
The APIs require an additional thread parameter
when the user of these APIs wishes to perform
thread specific manipulations on the tracing instances.
The patch also includes the corresponding
python wrappers for the C++ based APIs.

[ravitheja]

Hello,

I am working to enable support for Processor Trace in LLDB. Last year I had received recommendations on the lldb mailing list on how this should/could be done. To summarize, the functionality is as follows ->

• The actual trace gathering and OS specific trace handling is implemented in the server.
• We have a generic trace abstraction at the SB API and remote packet level.
• The lldb-server will conform to the trace abstraction so that trace technology and OS specific details can be contained in the lldb-server.
• The actual trace interpretation will be left to tools existing outside lldb which will use the SB API's to obtain raw trace data and interpret it.
• The trace architecture provides the possibility of adding support for multiple trace types without lldb having to interpret it (this also prevents lldb code base to bloat up due to support of several trace technologies).

The complete patch is too big hence I have made the following three patches ->

• The first patch adds support for generic SB APIs for trace.
• Second one will introduce generic remote packets.
• The last one adds Processor Trace support for Linux in lldb-server.

[clayborg]

Overall comments:

• Check the SB API guidelines and submit new patch (https://lldb.llvm.org/SB-api-coding-rules.html)
• It might be nice to make a lldb_private::Trace and a lldb::SBTrace object and have that be the object we used instead of adding many calls to SBProcess. You get a SBTrace object out of a SBProcess with:

class SBProcess
{
  SBTrace StartTrace(SBTraceOptions &opts, SBError &error);
  SBTrace GetTrace(); // Get current trace object, might return invalid/empty SBTrace object
};

Then all calls to start, stop, get config, get data, get metadata, are on the SBTrace object.

See inlined comments for all the details.

include/lldb/API/SBProcess.h

240

remove "sb" from name

243–244

Custom parameters should be passed in via JSON. This allows much more structured data and allows more complex settings to be specified.

257

remove "sb" from name

268

Remove "sb" from the variable names.

268

Should we return a trace object instead of a tracing ID? Maybe return a SBTrace object?

269

Should the thread be in the SBTraceOptions? What if you want to trace N threads, but not all? Seems like this would be better represented in the SBTraceOptions.

278

remove "sb" from name

281–288

Should we make a SBTraceData object instead of getting a buffer of bytes? I haven't looked past this code to the code below, so I am not sure how this data will be used. Just thinking out loud here.

290–291

Should the trace data not be a stream? Can you elaborate on why you think you need the offset?

304

If we return an SBTrace object from SBProcess:: StartTrace() then this function would be moved to the SBTrace object

313

If we return an SBTrace object from SBProcess:: StartTrace() then this function would be moved to the SBTrace object

342

If we return an SBTrace object from SBProcess:: StartTrace() then this function would be moved to the SBTrace object

include/lldb/API/SBTraceOptions.h

22–26

Generally anything in the lldb::SB* API we don't inline anything. If you change your implementation, you can have clients break.

Please read the SB API guidelines: https://lldb.llvm.org/SB-api-coding-rules.html

There are many violations of this in this file that will need to get fixed.

61–65

After reading SB API guidelines, you will need to move all member variables into an Impl class above and replace with a std::unique_ptr or std::shared_ptr to your Impl class that will contain these items. Let me know if the SB API guidelines aren't clear on why this is needed. You might want to just make it a std::unique_ptr to your TraceOptions class below.

include/lldb/Host/common/NativeProcessProtocol.h

335 ↗

(On Diff #87206)

Use a lldb_private::StructuredData::Dictionary here. This will allow the types to be passed in as JSON.

361 ↗

(On Diff #87206)

Either rename the TraceOptions class to Trace, or keep the TraceOptions and make a new Trace class that takes a TraceOptions class during construction. I would vote to just have a Trace class. Seems weird to have a TraceOptions::StartTracing(...) function.

374 ↗

(On Diff #87206)

Ditto above comment.

396 ↗

(On Diff #87206)

Ditto

481 ↗

(On Diff #87206)

Should this be:

std::shared_ptr<lldb_private::Trace m_trace_sp;

This gives ownership to this plug-in? Otherwise what happens when a process goes away? If we forget to clean it up we would leak it?

include/lldb/Target/Process.h

97

Change to be:

lldb_private::StructuredData::Dictionary m_trace_params;

This will allow trace params to be specified as JSON.

2783–2787

return a "std::shared_ptr<Trace>" or lldb::TraceSP which is a typedef to the previous shared pointer?

scripts/interface/SBProcess.i

411–425

It would be nice to have just:

class SBProcess
{
  // Start tracing and get the trace object back
  SBTrace StartTrace(SBTraceOptions &options, lldb::SBError &error);
  // Get any existing trace object in the process
  SBTrace SBProcess::GetTrace();
};

Then move have:

class SBTrace
{
  void GetConfig(..., lldb::tid_t thread_id);
  SBError StartTrace(lldb::tid_t thread_id);
  SBError StopTrace(lldb::tid_t thread_id);
  size_t GetData(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);
};

scripts/interface/SBTraceOptions.i

13

Adjust as needed from above comments.

[ravitheja]

Changes according to the comments.

[ravitheja]

include/lldb/API/SBProcess.h

269

We wanted to keep some symmetry among the APIs , the threadid could go in the TraceOptions as well.

281–288

So the idea we have is that we don't want to interpret the trace data inside lldb. Now one could go and make a class SBTraceData but it would just be a buffer of trace data, which is why we left it as a buffer of bytes.

290–291

For processor Trace implementation buffer was more suitable for decoding purposes. The reason for offset was that it gives the plugin the chance to request partial segments of the trace data which it could decode.

[jingham]

Greg is taking a couple of weeks off between jobs, so he may not get to this right away. But it should wait on his approval since he had substantial comments.

I'm pretty sure Kate isn't doing any work on lldb these days, I wouldn't wait on her to review patches.

[clayborg]

Much better. Found some extra stuff. In general we should be using SBStructuredData when ever we want to get/set stuff from structured data like JSON, XML or Apple plist, etc. If we make the APIs use SBStructuredData instead of using a SBStream, we can add constructors to SBStructuredData to init with JSON, XML, Apple plist, and more. All this will be parsed into a SBStructuredData or StructuredData::ObjectSP underneath, and then all people will use the StructuredData::ObjectSP on the inside.

include/lldb/API/SBProcess.h

267

Seems like the thread_id should go into the SBTraceOptions.

include/lldb/API/SBTrace.h

17

Remove SB from SBTraceImpl. Anything "SB" prefixed should be in the lldb namespace and should be exported, This shouldn't be exported.

98–100

Do the SBTraceOptions allow you to specify different things for different threads? If not, this parameter probably isn't needed, or could be extracted from the SBTraceOptions class itself. Seems like this isn't needed.

110

Use TraceImpl instead of SBTraceImpl

include/lldb/API/SBTraceOptions.h

32

Seems like this might be better as:

lldb::SBStructuredData getTraceParams(lldb::SBError &error);

The SBStructuredData can then emit to JSON or XML or any other format eventually.

39

This should probably be:

void setTraceParams(lldb::SBStructuredData &params);

Then we can add extra functions to SBStructuredData that allow you construct one from XML, JSON, Apple plist, or any other structured data.

53

We should move this typedef into lldb-forward.h

54

If we move this to lldb-forward.h, this will become "lldb::TraceOptionsSP"

include/lldb/Target/Process.h

80

We should start with SBStructuredData from the API, and then this function will just take a StructuredData::ObjectSP dict_obj

include/lldb/lldb-enumerations.h

721

Maybe a bit more documentation here for eTraceTypeProcessorTrace? Saying something like "this requests the raw trace buffer bytes from what ever CPU you are using, ...".

scripts/interface/SBTrace.i

13

Do we want something in here that explains what kind of trace buffer data you will be getting? I am thinking that even though we know we ask for "eTraceTypeProcessorTrace", this might not be enough for a plug-in to interpret these bytes. Do we need something like:

class SBTrace {
const char *GetTraceDataName();
};

And for intel it might return "intel processor trace version 2.0"? Or Maybe it would. be better as:

class SBTrace {
lldb::SBStructuredData GetTraceDataInfo();
};

This could return data that could be accessed as JSON. The version could be encoded in here. Maybe the exact CPU type, or CPU ID could also be encoded. I am guessing that the intel processor trace has already changed format from CPU to CPU and might also change in the future? This would help the plug-in that will interpret the trace byte to extract them correctly?

scripts/interface/SBTraceOptions.i

23

Use lldb::SBStructuredData instead of SBStream

source/API/SBTrace.cpp

31

We should use the new LLDB_LOG macros for all new logging.

34–35

We should use the new LLDB_LOG macros for all new logging.

42–44

ditto

56–57

We should use the new LLDB_LOG macros for all new logging.

65–67

ditto

77–78

We should use the new LLDB_LOG macros for all new logging.

124–127

Isn't one of these redundant?

source/API/SBTraceOptions.cpp

38

use SBStructuredData

55

use SBStructuredData

[ravitheja]

include/lldb/API/SBTraceOptions.h

39

Hi, this would also mean we make SBTraceOptions a friend class of SBStructuredData so that we can get access to the StructuredDataObject inside ?

[clayborg]

include/lldb/API/SBTraceOptions.h

39

Yeah you need a way for internal clients to get the StructuredData::ObjectSP from the SBStructuredData. You probably need to allow access to the StructuredDataImpl class that is currently defined in SBStructuredData.cpp. So a few things need to happen:

• move StructuredDataImpl somewhere into its own internal header file so that other clients in LLDB can access it
• make a protected member function in SBStructuredData that hands out a "StructuredDataImpl *" to allow clients to access it
• anyone that needs to get to the StructuredData::ObjectSP will then call a new accessor that must be added on StructuredDataImpl to retrieve it
• add new ways to load the SBStructuredData from JSON (something like SBStructuredData::SetFromJSON(...))

[ravitheja]

scripts/interface/SBTrace.i

13

Hello, Couldn't this be done in the GetTraceConfig (currently I am doing this) , as the TraceOptions already has a StructuredData for custom parameters and configurations, any trace technology could just convey any special or trace specific configurations in the custom parameters of TraceOptions ?

[ravitheja]

Changes for review.

[clayborg]

Very close. A few main things:

• JSON should use dictionaries and key/value pairs for all of the settings. Not sure if it was a typo where JSON array was mentioned a bunch of times?
• Custom settings should be in a dictionary within the JSON using the plug-in's name as the key This allows us to easily detect which settings are supposed to be custom. Any custom settings must be understood or we get an error back.
• New header file for TraceOptions

Other comments are inlined. But this is very close. Sorry for the delay in reviewing. Feel free to ping earlier if this happens again (after a day of no review)

include/lldb/API/SBProcess.h

241

Change "TraceOptions" to "trace options" since we are not mentioning the class name here.

243

The settings should be a JSON dictionary. I am hoping the JSON array above is a typo? If not we should fix this.

251

Is GetTraceConfig an internal API? If so, lets not mention it here. You general comments should suffice.

252–253

If might be nice to say "any custom parameters should be passed in a dictionary within the main JSON dictionary using the plugin name as the key. If your tracing plugin is named "intel-trace", then your JSON could look like:

{ "buffer-size" : 123, "intel-trace : { "custom-param-1" : 123, "custom-param2" : 234 }}

include/lldb/API/SBStructuredData.h

41–45

It is dangerous to change the API like this since we have code the links against the old unique_ptr and might do the wrong thing if an older binary links against a newer LLDB. Do you really need this changed? All parameters should be "SBStructuredData &" so there should be no copying on the way in...

include/lldb/API/SBTraceOptions.h

20–22

I would make two copies: one default and the one that takes params. Default values can cause problems in the future if any new params are added before the existing ones. I am also fine just having the default version and requiring people to call the setters. I will leave that decision up to you

31

JSON dictionary. The dict can contain an array, but everything should be key/value pairs in JSON.

38

JSON dictionary.

include/lldb/Target/Process.h

61

We should make a TraceOptions.h header file for this class

62–65

avoid default params.

include/lldb/lldb-enumerations.h

733

Should we be this specific with this define? Many processors have processor trace. We could start a trace with SBTraceOptions and then get a SBTrace object back, then ask SBTrace::GetPluginName() to get back "intel-processor-trace". I would prefer to keep the enum generic since that allows to easier merging in the future. We will want to expose ARM trace and other trace types in the future and we don't want everyone to have to edit this file and add their enum here. So I would make the GetTraceConfig() or SBTrace::GetPluginName() return the name of the trace, which will allow you to abstractly return the data and abstractly request tracing.

[ravitheja]

New diff with requested changes.

[ravitheja]

include/lldb/API/SBProcess.h

251

No, its not an internal API, so just to throw some light to it, Processor trace integration for Linux does not support all buffer sizes so we are rounding the buffer sizes to the nearest supported buffer size and through GetTraceConfig we plan to communicate the actual trace buffer size being.

[clayborg]

Looks good, lets start with this and iterate.

[ravitheja]

Fixing few header file inclusions.

include/lldb/API/LLDB.h

 #include "lldb/API/SBStructuredData.h"
 #include "lldb/API/SBSymbol.h"
 #include "lldb/API/SBSymbolContext.h"
 #include "lldb/API/SBSymbolContextList.h"
 #include "lldb/API/SBTarget.h"
 #include "lldb/API/SBThread.h"
 #include "lldb/API/SBThreadCollection.h"
 #include "lldb/API/SBThreadPlan.h"
+#include "lldb/API/SBTrace.h"
+#include "lldb/API/SBTraceOptions.h"
 #include "lldb/API/SBType.h"
 #include "lldb/API/SBTypeCategory.h"
 #include "lldb/API/SBTypeEnumMember.h"
 #include "lldb/API/SBTypeFilter.h"
 #include "lldb/API/SBTypeFormat.h"
 #include "lldb/API/SBTypeNameSpecifier.h"
 #include "lldb/API/SBTypeSummary.h"
 #include "lldb/API/SBTypeSynthetic.h"
 #include "lldb/API/SBUnixSignals.h"
 #include "lldb/API/SBValue.h"
 #include "lldb/API/SBValueList.h"
 #include "lldb/API/SBVariablesOptions.h"
 #include "lldb/API/SBWatchpoint.h"
 
 #endif // LLDB_LLDB_h_

include/lldb/API/SBDefines.h

 class LLDB_API SBStructuredData;
 class LLDB_API SBSymbol;
 class LLDB_API SBSymbolContext;
 class LLDB_API SBSymbolContextList;
 class LLDB_API SBTarget;
 class LLDB_API SBThread;
 class LLDB_API SBThreadCollection;
 class LLDB_API SBThreadPlan;
+class LLDB_API SBTrace;
+class LLDB_API SBTraceOptions;
 class LLDB_API SBType;
 class LLDB_API SBTypeCategory;
 class LLDB_API SBTypeEnumMember;
 class LLDB_API SBTypeEnumMemberList;
 class LLDB_API SBTypeFilter;
 class LLDB_API SBTypeFormat;
 class LLDB_API SBTypeMemberFunction;
 class LLDB_API SBTypeNameSpecifier;

include/lldb/API/SBError.h

protected:
   friend class SBData;
   friend class SBDebugger;
   friend class SBCommunication;
   friend class SBHostOS;
   friend class SBPlatform;
   friend class SBProcess;
   friend class SBStructuredData;
   friend class SBThread;
+  friend class SBTrace;
   friend class SBTarget;
   friend class SBValue;
   friend class SBWatchpoint;
   friend class SBBreakpoint;
   friend class SBBreakpointLocation;
 
   lldb_private::Error *get();
 

include/lldb/API/SBProcess.h

public:
   static bool EventIsStructuredDataEvent(const lldb::SBEvent &event);
 
   lldb::SBBroadcaster GetBroadcaster() const;
 
   static const char *GetBroadcasterClass();
 
   bool GetDescription(lldb::SBStream &description);
 
+  //------------------------------------------------------------------
+  /// 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.
+  //------------------------------------------------------------------
+  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
   ///     to load.
   ///
   /// @param[out] error
   ///     An error object that gets filled in with any errors that
   ///     might occur when trying to load the shared library.
   ///
   /// @return
   ///     A token that represents the shared library that can be
   ///     later used to unload the shared library. A value of
   ///     LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
   ///     library can't be opened.
   //------------------------------------------------------------------
   uint32_t LoadImage(lldb::SBFileSpec &remote_image_spec, lldb::SBError &error);
 
   //------------------------------------------------------------------
   /// Load a shared library into this process.
   ///
   /// @param[in] local_image_spec
   ///     The file spec that points to the shared library that you
   ///     want to load if the library is located on the host. The
   ///     library will be copied over to the location specified by
   ///     remote_image_spec or into the current working directory with
   ///     the same filename if the remote_image_spec isn't specified.
   ///
   /// @param[in] remote_image_spec
   ///     If local_image_spec is specified then the location where the
   ///     library should be copied over from the host. If
   ///     local_image_spec isn't specified, then the path for the
   ///     shared library on the target what you want to load.
   ///
   /// @param[out] error
   ///     An error object that gets filled in with any errors that
   ///     might occur when trying to load the shared library.
   ///
   /// @return
   ///     A token that represents the shared library that can be
   ///     later used to unload the shared library. A value of
   ///     LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
   ///     library can't be opened.
   //------------------------------------------------------------------
   uint32_t LoadImage(const lldb::SBFileSpec &local_image_spec,
                      const lldb::SBFileSpec &remote_image_spec,
                      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.
public:
   //------------------------------------------------------------------
   /// Return the name of one of the thread-origin extended backtrace
   /// methods.
   ///
   /// @param [in] idx
   ///   The index of the name to return.  They will be returned in
   ///   the order that the user will most likely want to see them.
   ///   e.g. if the type at index 0 is not available for a thread,
   ///   see if the type at index 1 provides an extended backtrace.
   ///
   /// @return
   ///   The name at that index.
   //------------------------------------------------------------------
   const char *GetExtendedBacktraceTypeAtIndex(uint32_t idx);
 
   lldb::SBThreadCollection GetHistoryThreads(addr_t addr);
 

include/lldb/API/SBStructuredData.h

 //===-- SBStructuredData.h --------------------------------------*- C++ -*-===//
 //
 //                     The LLVM Compiler Infrastructure
 //
 // This file is distributed under the University of Illinois Open Source
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef SBStructuredData_h
 #define SBStructuredData_h
 
 #include "lldb/API/SBDefines.h"
 #include "lldb/API/SBModule.h"
 
-class StructuredDataImpl;
-
 namespace lldb {
 
 class SBStructuredData {
 public:
   SBStructuredData();
 
   SBStructuredData(const lldb::SBStructuredData &rhs);
 
   SBStructuredData(const lldb::EventSP &event_sp);
 
   ~SBStructuredData();
 
   lldb::SBStructuredData &operator=(const lldb::SBStructuredData &rhs);
 
   bool IsValid() const;
 
+  lldb::SBError SetFromJSON(lldb::SBStream &stream);
+
   void Clear();
 
   lldb::SBError GetAsJSON(lldb::SBStream &stream) const;
 
   lldb::SBError GetDescription(lldb::SBStream &stream) const;
 
-private:
-  std::unique_ptr<StructuredDataImpl> m_impl_up;
+protected:
+  friend class SBTraceOptions;
+
+  StructuredDataImplUP m_impl_up;
 };
 }
 
 #endif /* SBStructuredData_h */

include/lldb/API/SBTrace.h

+//===-- SBTrace.h -----------------------------------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLDB_SBTrace_h_
+#define LLDB_SBTrace_h_
+
+#include "lldb/API/SBDefines.h"
+#include "lldb/API/SBError.h"
+
+class TraceImpl;
+
+namespace lldb {
+
+class LLDB_API SBTrace {
+public:
+  SBTrace();
+  //------------------------------------------------------------------
+  /// 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.
+  ///
+  /// @param[in] size
+  ///     The size of the buffer used to read the data. This is
+  ///     also the size of the data intended to read. It is also
+  ///     possible to partially read the trace data for some trace
+  ///     technologies by specifying a smaller buffer.
+  ///
+  /// @param[in] offset
+  ///     The start offset to begin reading the trace data.
+  ///
+  /// @param[in] thread_id
+  ///     Tracing could be started for the complete process or a
+  ///     single thread, in the first case the uid obtained would
+  ///     map to all the threads existing within the process and the
+  ///     ones spawning later. The thread_id parameter can be used in
+  ///     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);
+
+  //------------------------------------------------------------------
+  /// Stop the tracing instance. Stopping the trace will also
+  /// lead to deletion of any gathered trace data.
+  ///
+  /// @param[out] error
+  ///     An error explaining what went wrong.
+  ///
+  /// @param[in] thread_id
+  ///     The user 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 uid
+  ///     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 uid 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.
+  //------------------------------------------------------------------
+  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.
+  ///
+  /// @param[out] error
+  ///     An error explaining what went wrong.
+  //------------------------------------------------------------------
+  void GetTraceConfig(SBTraceOptions &options, SBError &error);
+
+  lldb::user_id_t GetTraceUID();
+
+  bool IsValid();
+
+protected:
+  typedef std::shared_ptr<TraceImpl> TraceImplSP;
+
+  friend class SBProcess;
+
+  void SetTraceUID(lldb::user_id_t uid);
+
+  TraceImplSP m_trace_impl_sp;
+
+  lldb::ProcessSP GetSP() const;
+
+  void SetSP(const ProcessSP &process_sp);
+
+  lldb::ProcessWP m_opaque_wp;
+};
+} // namespace lldb
+
+#endif // LLDB_SBTrace_h_

include/lldb/API/SBTraceOptions.h

+//===-- SBTraceOptions ------------------------------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef SBTRACEOPTIONS_H_
+#define SBTRACEOPTIONS_H_
+
+#include "lldb/API/SBDefines.h"
+
+namespace lldb {
+
+class LLDB_API SBTraceOptions {
+public:
+  SBTraceOptions();
+
+  lldb::TraceType getType() const;
+
+  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.
+  lldb::SBStructuredData getTraceParams(lldb::SBError &error);
+
+  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.
+  void setTraceParams(lldb::SBStructuredData &params);
+
+  void setType(lldb::TraceType type);
+
+  void setTraceBufferSize(uint64_t size);
+
+  void setMetaDataBufferSize(uint64_t size);
+
+  void setThreadID(lldb::tid_t thread_id);
+
+  lldb::tid_t getThreadID();
+
+  bool IsValid();
+
+protected:
+  friend class SBProcess;
+  friend class SBTrace;
+
+  lldb::TraceOptionsSP m_traceoptions_sp;
+};
+}
+
+#endif /* SBTRACEOPTIONS_H_ */

include/lldb/Core/StructuredDataImpl.h

+//===-- StructuredDataImpl.h ------------------------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef liblldb_StructuredDataImpl_h_
+#define liblldb_StructuredDataImpl_h_
+
+#include "lldb/Core/Event.h"
+#include "lldb/Core/StructuredData.h"
+#include "lldb/Utility/Error.h"
+#include "lldb/Utility/Stream.h"
+#include "lldb/Target/StructuredDataPlugin.h"
+#include "lldb/lldb-forward.h"
+
+#pragma mark--
+#pragma mark StructuredDataImpl
+
+namespace lldb_private {
+
+class StructuredDataImpl {
+public:
+  StructuredDataImpl() : m_plugin_wp(), m_data_sp() {}
+
+  StructuredDataImpl(const StructuredDataImpl &rhs) = default;
+
+  StructuredDataImpl(const lldb::EventSP &event_sp)
+      : m_plugin_wp(
+            EventDataStructuredData::GetPluginFromEvent(event_sp.get())),
+        m_data_sp(EventDataStructuredData::GetObjectFromEvent(event_sp.get())) {
+  }
+
+  ~StructuredDataImpl() = default;
+
+  StructuredDataImpl &operator=(const StructuredDataImpl &rhs) = default;
+
+  bool IsValid() const { return m_data_sp.get() != nullptr; }
+
+  void Clear() {
+    m_plugin_wp.reset();
+    m_data_sp.reset();
+  }
+
+  Error GetAsJSON(Stream &stream) const {
+    Error error;
+
+    if (!m_data_sp) {
+      error.SetErrorString("No structured data.");
+      return error;
+    }
+
+    m_data_sp->Dump(stream);
+    return error;
+  }
+
+  Error GetDescription(Stream &stream) const {
+    Error error;
+
+    if (!m_data_sp) {
+      error.SetErrorString("Cannot pretty print structured data: "
+                           "no data to print.");
+      return error;
+    }
+
+    // Grab the plugin.
+    auto plugin_sp = lldb::StructuredDataPluginSP(m_plugin_wp);
+    if (!plugin_sp) {
+      error.SetErrorString("Cannot pretty print structured data: "
+                           "plugin doesn't exist.");
+      return error;
+    }
+
+    // Get the data's description.
+    return plugin_sp->GetDescription(m_data_sp, stream);
+  }
+
+  StructuredData::ObjectSP GetObjectSP() {
+    return m_data_sp;
+  }
+
+  void SetObjectSP(const StructuredData::ObjectSP &obj) {
+    m_data_sp = obj;
+  }
+
+private:
+
+  lldb::StructuredDataPluginWP m_plugin_wp;
+  StructuredData::ObjectSP m_data_sp;
+};
+}
+#endif

include/lldb/Core/TraceOptions.h

+//===-- TraceOptions.h ------------------------------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef liblldb_TraceOptions_h_
+#define liblldb_TraceOptions_h_
+
+#include "lldb/lldb-defines.h"
+#include "lldb/lldb-enumerations.h"
+
+#include "lldb/Core/StructuredData.h"
+
+namespace lldb_private {
+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() { 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;
+};
+}
+
+#endif // liblldb_TraceOptions_h_
 No newline at end of file

include/lldb/Target/Process.h

 #include "lldb/Core/Broadcaster.h"
 #include "lldb/Core/Communication.h"
 #include "lldb/Core/Event.h"
 #include "lldb/Core/Listener.h"
 #include "lldb/Core/LoadedModuleInfoList.h"
 #include "lldb/Core/PluginInterface.h"
 #include "lldb/Core/StructuredData.h"
 #include "lldb/Core/ThreadSafeValue.h"
+#include "lldb/Core/TraceOptions.h"
 #include "lldb/Core/UserSettingsController.h"
 #include "lldb/Host/HostThread.h"
 #include "lldb/Host/ProcessRunLock.h"
 #include "lldb/Interpreter/Options.h"
 #include "lldb/Target/ExecutionContextScope.h"
 #include "lldb/Target/InstrumentationRuntime.h"
 #include "lldb/Target/Memory.h"
 #include "lldb/Target/ProcessInfo.h"
 #include "lldb/Target/ProcessLaunchInfo.h"
 #include "lldb/Target/QueueList.h"
 #include "lldb/Target/ThreadList.h"
 #include "lldb/Utility/Error.h"
 #include "lldb/Utility/NameMatches.h"
 #include "lldb/lldb-private.h"
 
 #include "llvm/ADT/ArrayRef.h"
 
 namespace lldb_private {
 
 template <typename B, typename S> struct Range;
 
 //----------------------------------------------------------------------
 // ProcessProperties
 //----------------------------------------------------------------------
 class ProcessProperties : public Properties {
 public:
   // Pass nullptr for "process" if the ProcessProperties are to be the global
   // copy
   ProcessProperties(lldb_private::Process *process);
 
   ~ProcessProperties() override;
 
   bool GetDisableMemoryCache() const;
 
   uint64_t GetMemoryCacheLineSize() const;
 
   Args GetExtraStartupCommands() const;
 
   void SetExtraStartupCommands(const Args &args);
 
   FileSpec GetPythonOSPluginPath() const;
 
   void SetPythonOSPluginPath(const FileSpec &file);
 
   bool GetIgnoreBreakpointsInExpressions() const;
 
   void SetIgnoreBreakpointsInExpressions(bool ignore);
 
   bool GetUnwindOnErrorInExpressions() const;
 
   void SetUnwindOnErrorInExpressions(bool ignore);
 
   bool GetStopOnSharedLibraryEvents() const;
 
   void SetStopOnSharedLibraryEvents(bool stop);
 
   bool GetDetachKeepsStopped() const;
 
   void SetDetachKeepsStopped(bool keep_stopped);
 
   bool GetWarningsOptimization() const;
 
 protected:
   static void OptionValueChangedCallback(void *baton,
                                          OptionValue *option_value);
 

   ///
   /// @return
   ///     The plugin if one is available for the specified feature;
   ///     otherwise, returns an empty shared pointer.
   //------------------------------------------------------------------
   lldb::StructuredDataPluginSP
   GetStructuredDataPlugin(const ConstString &type_name) const;
 
+  //------------------------------------------------------------------
+  /// 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(lldb::TraceOptionsSP &options,
+                                     Error &error) {
+    error.SetErrorString("Not implemented");
+    return LLDB_INVALID_UID;
+  }
+
+  //------------------------------------------------------------------
+  /// 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 void StopTrace(lldb::user_id_t uid, lldb::tid_t thread_id,
+                         Error &error) {
+    error.SetErrorString("Not implemented");
+  }
+
+  //------------------------------------------------------------------
+  /// 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 size_t GetData(lldb::user_id_t uid, lldb::tid_t thread_id,
+                         Error &error, void *buf, size_t size,
+                         size_t offset = 0) {
+    error.SetErrorString("Not implemented");
+    return 0;
+  }
+
+  //------------------------------------------------------------------
+  /// Similar API as above except for obtaining meta data
+  //------------------------------------------------------------------
+  virtual size_t GetMetaData(lldb::user_id_t uid, lldb::tid_t thread_id,
+                             Error &error, void *buf, size_t size,
+                             size_t offset = 0) {
+    error.SetErrorString("Not implemented");
+    return 0;
+  }
+
+  //------------------------------------------------------------------
+  /// API to obtain the trace configuration used by a trace instance.
+  /// Configurations that may be specific to some trace technology
+  /// should be stored in the custom parameters. The options are
+  /// transported to the server, which shall interpret accordingly.
+  /// The thread_id can be specified in the options to obtain the
+  /// configuration used by a specific thread. The thread_id specified
+  /// should also match the uid otherwise an error will be returned.
+  //------------------------------------------------------------------
+  virtual void GetTraceConfig(lldb::user_id_t uid, Error &error,
+                              lldb::TraceOptionsSP &options) {
+    error.SetErrorString("Not implemented");
+    return;
+  }
+
 protected:
   void SetState(lldb::EventSP &event_sp);
 
   lldb::StateType GetPrivateState();
 
   //------------------------------------------------------------------
   /// The "private" side of resuming a process.  This doesn't alter the
   /// state of m_run_lock, but just causes the process to resume.

include/lldb/lldb-enumerations.h

enum BasicType {
   eBasicTypeLongDoubleComplex,
   eBasicTypeObjCID,
   eBasicTypeObjCClass,
   eBasicTypeObjCSel,
   eBasicTypeNullPtr,
   eBasicTypeOther
 };
 
+enum TraceType {
+  eTraceTypeNone = 0,
+
+  // Hardware Trace generated by the processor.
+  eTraceTypeProcessorTrace
+};
+
 FLAGS_ENUM(TypeClass){
     eTypeClassInvalid = (0u), eTypeClassArray = (1u << 0),
     eTypeClassBlockPointer = (1u << 1), eTypeClassBuiltin = (1u << 2),
     eTypeClassClass = (1u << 3), eTypeClassComplexFloat = (1u << 4),
     eTypeClassComplexInteger = (1u << 5), eTypeClassEnumeration = (1u << 6),
     eTypeClassFunction = (1u << 7), eTypeClassMemberPointer = (1u << 8),
     eTypeClassObjCObject = (1u << 9), eTypeClassObjCInterface = (1u << 10),
     eTypeClassObjCObjectPointer = (1u << 11), eTypeClassPointer = (1u << 12),
     eTypeClassReference = (1u << 13), eTypeClassStruct = (1u << 14),
     eTypeClassTypedef = (1u << 15), eTypeClassUnion = (1u << 16),
     eTypeClassVector = (1u << 17),
     // Define the last type class as the MSBit of a 32 bit value
     eTypeClassOther = (1u << 31),
     // Define a mask that can be used for any type when finding types

include/lldb/lldb-forward.h

 class StoppointCallbackContext;
 class StoppointLocation;
 class Stream;
 template <unsigned N> class StreamBuffer;
 class StreamFile;
 class StreamString;
 class StringList;
 struct StringSummaryFormat;
+class StructuredDataImpl;
 class StructuredDataPlugin;
 class SystemRuntime;
 class TypeSummaryImpl;
 class TypeSummaryOptions;
 class Symbol;
 class SymbolContext;
 class SymbolContextList;
 class SymbolContextScope;

 class ThreadPlanRunToAddress;
 class ThreadPlanStepInstruction;
 class ThreadPlanStepOut;
 class ThreadPlanStepOverBreakpoint;
 class ThreadPlanStepRange;
 class ThreadPlanStepThrough;
 class ThreadPlanTracer;
 class ThreadSpec;
+class TraceOptions;
 class Type;
 class TypeAndOrName;
 class TypeCategoryMap;
 class TypeImpl;
 class TypeList;
 class TypeMap;
 class TypeListImpl;
 class TypeMemberImpl;

 typedef std::shared_ptr<lldb_private::StackFrameList> StackFrameListSP;
 typedef std::shared_ptr<lldb_private::StopInfo> StopInfoSP;
 typedef std::shared_ptr<lldb_private::StoppointLocation> StoppointLocationSP;
 typedef std::shared_ptr<lldb_private::Stream> StreamSP;
 typedef std::weak_ptr<lldb_private::Stream> StreamWP;
 typedef std::shared_ptr<lldb_private::StreamFile> StreamFileSP;
 typedef std::shared_ptr<lldb_private::StringSummaryFormat>
     StringTypeSummaryImplSP;
+typedef std::unique_ptr<lldb_private::StructuredDataImpl> StructuredDataImplUP;
 typedef std::shared_ptr<lldb_private::StructuredDataPlugin>
     StructuredDataPluginSP;
 typedef std::weak_ptr<lldb_private::StructuredDataPlugin>
     StructuredDataPluginWP;
 typedef std::shared_ptr<lldb_private::SymbolFile> SymbolFileSP;
 typedef std::shared_ptr<lldb_private::SymbolFileType> SymbolFileTypeSP;
 typedef std::weak_ptr<lldb_private::SymbolFileType> SymbolFileTypeWP;
 typedef std::shared_ptr<lldb_private::SymbolContextSpecifier>
     SymbolContextSpecifierSP;
 typedef std::unique_ptr<lldb_private::SymbolVendor> SymbolVendorUP;
 typedef std::shared_ptr<lldb_private::SyntheticChildren> SyntheticChildrenSP;
 typedef std::shared_ptr<lldb_private::SyntheticChildrenFrontEnd>
     SyntheticChildrenFrontEndSP;
 typedef std::shared_ptr<lldb_private::Target> TargetSP;
 typedef std::weak_ptr<lldb_private::Target> TargetWP;
 typedef std::shared_ptr<lldb_private::TargetProperties> TargetPropertiesSP;
 typedef std::shared_ptr<lldb_private::Thread> ThreadSP;
 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::ThreadPlanTracer> ThreadPlanTracerSP;
+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;

scripts/interface/SBProcess.i

public:
     GetHistoryThreads (addr_t addr);
              
     bool
     IsInstrumentationRuntimePresent(lldb::InstrumentationRuntimeType type);
 
     lldb::SBError
     SaveCore(const char *file_name);
 
+    lldb::SBTrace
+    StartTrace(SBTraceOptions &options, lldb::SBError &error);
+
     lldb::SBError
     GetMemoryRegionInfo(lldb::addr_t load_addr, lldb::SBMemoryRegionInfo &region_info);
 
     lldb::SBMemoryRegionInfoList
     GetMemoryRegions();
 
     %pythoncode %{
         def __get_is_alive__(self):
             '''Returns "True" if the process is currently alive, "False" otherwise'''
             s = self.GetState()
             if (s == eStateAttaching or 
                 s == eStateLaunching or 
                 s == eStateStopped or 
                 s == eStateRunning or 
                 s == eStateStepping or 
                 s == eStateCrashed or 
                 s == eStateSuspended):
                 return True
             return False
 

scripts/interface/SBStructuredData.i

public:
         void
         Clear();
 
         lldb::SBError
         GetAsJSON(lldb::SBStream &stream) const;
 
         lldb::SBError
         GetDescription(lldb::SBStream &stream) const;
+
+        lldb::SBError
+        SetFromJSON(lldb::SBStream &stream);
     };
 }

scripts/interface/SBTrace.i

+//===-- SWIG Interface for SBTrace.h ----------------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+namespace lldb {
+
+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);
+
+  void StopTrace(SBError &error,
+                 lldb::tid_t thread_id);
+
+  void GetTraceConfig(SBTraceOptions &options,
+                      SBError &error);
+
+  lldb::user_id_t GetTraceUID();
+
+  bool IsValid();
+
+};
+} // namespace lldb
 No newline at end of file

scripts/interface/SBTraceOptions.i

+//===-- SWIG Interface for SBTraceOptions -----------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+namespace lldb {
+
+class LLDB_API SBTraceOptions {
+public:
+  SBTraceOptions();
+
+  lldb::TraceType getType() const;
+
+  uint64_t getTraceBufferSize() const;
+
+  lldb::SBStructuredData getTraceParams(lldb::SBError &error);
+
+  uint64_t getMetaDataBufferSize() const;
+
+  void setTraceParams(lldb::SBStructuredData &params);
+
+  void setType(lldb::TraceType type);
+
+  void setTraceBufferSize(uint64_t size);
+
+  void setMetaDataBufferSize(uint64_t size);
+
+  void setThreadID(lldb::tid_t thread_id);
+
+  lldb::tid_t getThreadID();
+
+  bool IsValid();
+};
+}

scripts/lldb.swig

 #include "lldb/API/SBStructuredData.h"
 #include "lldb/API/SBSymbol.h"
 #include "lldb/API/SBSymbolContext.h"
 #include "lldb/API/SBSymbolContextList.h"
 #include "lldb/API/SBTarget.h"
 #include "lldb/API/SBThread.h"
 #include "lldb/API/SBThreadCollection.h"
 #include "lldb/API/SBThreadPlan.h"
+#include "lldb/API/SBTrace.h"
+#include "lldb/API/SBTraceOptions.h"
 #include "lldb/API/SBType.h"
 #include "lldb/API/SBTypeCategory.h"
 #include "lldb/API/SBTypeEnumMember.h"
 #include "lldb/API/SBTypeFilter.h"
 #include "lldb/API/SBTypeFormat.h"
 #include "lldb/API/SBTypeNameSpecifier.h"
 #include "lldb/API/SBTypeSummary.h"
 #include "lldb/API/SBTypeSynthetic.h"

 %include "./interface/SBStructuredData.i"
 %include "./interface/SBSymbol.i"
 %include "./interface/SBSymbolContext.i"
 %include "./interface/SBSymbolContextList.i"
 %include "./interface/SBTarget.i"
 %include "./interface/SBThread.i"
 %include "./interface/SBThreadCollection.i"
 %include "./interface/SBThreadPlan.i"
+%include "./interface/SBTrace.i"
+%include "./interface/SBTraceOptions.i"
 %include "./interface/SBType.i"
 %include "./interface/SBTypeCategory.i"
 %include "./interface/SBTypeEnumMember.i"
 %include "./interface/SBTypeFilter.i"
 %include "./interface/SBTypeFormat.i"
 %include "./interface/SBTypeNameSpecifier.i"
 %include "./interface/SBTypeSummary.i"
 %include "./interface/SBTypeSynthetic.i"

source/API/CMakeLists.txt

add_lldb_library(liblldb SHARED
   SBStructuredData.cpp
   SBSymbol.cpp
   SBSymbolContext.cpp
   SBSymbolContextList.cpp
   SBTarget.cpp
   SBThread.cpp
   SBThreadCollection.cpp
   SBThreadPlan.cpp
+  SBTrace.cpp
+  SBTraceOptions.cpp
   SBType.cpp
   SBTypeCategory.cpp
   SBTypeEnumMember.cpp
   SBTypeFilter.cpp
   SBTypeFormat.cpp
   SBTypeNameSpecifier.cpp
   SBTypeSummary.cpp
   SBTypeSynthetic.cpp

source/API/SBProcess.cpp

 #include "lldb/API/SBFileSpec.h"
 #include "lldb/API/SBMemoryRegionInfo.h"
 #include "lldb/API/SBMemoryRegionInfoList.h"
 #include "lldb/API/SBStream.h"
 #include "lldb/API/SBStringList.h"
 #include "lldb/API/SBStructuredData.h"
 #include "lldb/API/SBThread.h"
 #include "lldb/API/SBThreadCollection.h"
+#include "lldb/API/SBTrace.h"
+#include "lldb/API/SBTraceOptions.h"
 #include "lldb/API/SBUnixSignals.h"
 
 using namespace lldb;
 using namespace lldb_private;
 
 SBProcess::SBProcess() : m_opaque_wp() {}
 
 //----------------------------------------------------------------------
log->Printf(
         "SBProcess(%p)::GetAsyncProfileData (dst=\"%.*s\", dst_len=%" PRIu64
         ") => %" PRIu64,
         static_cast<void *>(process_sp.get()), static_cast<int>(bytes_read),
         dst, static_cast<uint64_t>(dst_len), static_cast<uint64_t>(bytes_read));
 
   return bytes_read;
 }
 
+lldb::SBTrace SBProcess::StartTrace(SBTraceOptions &options,
+                                    lldb::SBError &error) {
+  Log *log(lldb_private::GetLogIfAllCategoriesSet(LIBLLDB_LOG_API));
+  ProcessSP process_sp(GetSP());
+  error.Clear();
+  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);
+    LLDB_LOG(log, "SBProcess::returned uid - %" PRIx64, uid);
+  }
+  return trace_instance;
+}
+
 void SBProcess::ReportEventState(const SBEvent &event, FILE *out) const {
   if (out == NULL)
     return;
 
   ProcessSP process_sp(GetSP());
   if (process_sp) {
     const StateType event_state = SBProcess::GetStateFromEvent(event);
     char message[1024];

source/API/SBStructuredData.cpp

 //===-- SBStructuredData.cpp ------------------------------------*- C++ -*-===//
 //
 //                     The LLVM Compiler Infrastructure
 //
 // This file is distributed under the University of Illinois Open Source
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/API/SBStructuredData.h"
 
 #include "lldb/API/SBStream.h"
 #include "lldb/Core/Event.h"
 #include "lldb/Core/StructuredData.h"
+#include "lldb/Core/StructuredDataImpl.h"
 #include "lldb/Target/StructuredDataPlugin.h"
 #include "lldb/Utility/Error.h"
 #include "lldb/Utility/Stream.h"
 
 using namespace lldb;
 using namespace lldb_private;
 
 #pragma mark--
-#pragma mark StructuredDataImpl
-
-class StructuredDataImpl {
-public:
-  StructuredDataImpl() : m_plugin_wp(), m_data_sp() {}
-
-  StructuredDataImpl(const StructuredDataImpl &rhs) = default;
-
-  StructuredDataImpl(const EventSP &event_sp)
-      : m_plugin_wp(
-            EventDataStructuredData::GetPluginFromEvent(event_sp.get())),
-        m_data_sp(EventDataStructuredData::GetObjectFromEvent(event_sp.get())) {
-  }
-
-  ~StructuredDataImpl() = default;
-
-  StructuredDataImpl &operator=(const StructuredDataImpl &rhs) = default;
-
-  bool IsValid() const { return m_data_sp.get() != nullptr; }
-
-  void Clear() {
-    m_plugin_wp.reset();
-    m_data_sp.reset();
-  }
-
-  SBError GetAsJSON(lldb_private::Stream &stream) const {
-    SBError sb_error;
-
-    if (!m_data_sp) {
-      sb_error.SetErrorString("No structured data.");
-      return sb_error;
-    }
-
-    m_data_sp->Dump(stream);
-    return sb_error;
-  }
-
-  Error GetDescription(lldb_private::Stream &stream) const {
-    Error error;
-
-    if (!m_data_sp) {
-      error.SetErrorString("Cannot pretty print structured data: "
-                           "no data to print.");
-      return error;
-    }
-
-    // Grab the plugin.
-    auto plugin_sp = StructuredDataPluginSP(m_plugin_wp);
-    if (!plugin_sp) {
-      error.SetErrorString("Cannot pretty print structured data: "
-                           "plugin doesn't exist.");
-      return error;
-    }
-
-    // Get the data's description.
-    return plugin_sp->GetDescription(m_data_sp, stream);
-  }
-
-private:
-  StructuredDataPluginWP m_plugin_wp;
-  StructuredData::ObjectSP m_data_sp;
-};
-
-#pragma mark--
 #pragma mark SBStructuredData
 
 SBStructuredData::SBStructuredData() : m_impl_up(new StructuredDataImpl()) {}
 
 SBStructuredData::SBStructuredData(const lldb::SBStructuredData &rhs)
     : m_impl_up(new StructuredDataImpl(*rhs.m_impl_up.get())) {}
 
 SBStructuredData::SBStructuredData(const lldb::EventSP &event_sp)
     : m_impl_up(new StructuredDataImpl(event_sp)) {}
 
 SBStructuredData::~SBStructuredData() {}
 
 SBStructuredData &SBStructuredData::
 operator=(const lldb::SBStructuredData &rhs) {
   *m_impl_up = *rhs.m_impl_up;
   return *this;
 }
 
+lldb::SBError SBStructuredData::SetFromJSON(lldb::SBStream &stream) {
+  lldb::SBError error;
+  std::string json_str(stream.GetData());
+
+  StructuredData::ObjectSP json_obj = StructuredData::ParseJSON(json_str);
+  m_impl_up->SetObjectSP(json_obj);
+
+  if (!json_obj || json_obj->GetType() != StructuredData::Type::eTypeDictionary)
+    error.SetErrorString("Invalid Syntax");
+  return error;
+}
+
 bool SBStructuredData::IsValid() const { return m_impl_up->IsValid(); }
 
 void SBStructuredData::Clear() { m_impl_up->Clear(); }
 
 SBError SBStructuredData::GetAsJSON(lldb::SBStream &stream) const {
-  return m_impl_up->GetAsJSON(stream.ref());
+  SBError error;
+  error.SetError(m_impl_up->GetAsJSON(stream.ref()));
+  return error;
 }
 
 lldb::SBError SBStructuredData::GetDescription(lldb::SBStream &stream) const {
   Error error = m_impl_up->GetDescription(stream.ref());
   SBError sb_error;
   sb_error.SetError(error);
   return sb_error;
 }

source/API/SBTrace.cpp

+//===-- SBTrace.cpp ---------------------------------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#include "lldb/Utility/Log.h"
+#include "lldb/Target/Process.h"
+
+#include "lldb/API/SBTrace.h"
+#include "lldb/API/SBTraceOptions.h"
+
+using namespace lldb;
+using namespace lldb_private;
+
+class TraceImpl {
+public:
+  lldb::user_id_t uid;
+};
+
+lldb::ProcessSP SBTrace::GetSP() const { return m_opaque_wp.lock(); }
+
+size_t SBTrace::GetTraceData(SBError &error, void *buf, size_t size,
+                             size_t offset, lldb::tid_t thread_id) {
+  size_t bytes_read = 0;
+  ProcessSP process_sp(GetSP());
+  Log *log(lldb_private::GetLogIfAllCategoriesSet(LIBLLDB_LOG_API));
+  error.Clear();
+
+  if (!process_sp) {
+    error.SetErrorString("invalid process");
+  } else {
+    bytes_read = process_sp->GetData(GetTraceUID(), thread_id, error.ref(), buf,
+                                     size, offset);
+    LLDB_LOG(log, "SBTrace::bytes_read - %" PRIx64, bytes_read);
+  }
+  return bytes_read;
+}
+
+size_t SBTrace::GetMetaData(SBError &error, void *buf, size_t size,
+                            size_t offset, lldb::tid_t thread_id) {
+  size_t bytes_read = 0;
+  ProcessSP process_sp(GetSP());
+  Log *log(lldb_private::GetLogIfAllCategoriesSet(LIBLLDB_LOG_API));
+  error.Clear();
+
+  if (!process_sp) {
+    error.SetErrorString("invalid process");
+  } else {
+
+    bytes_read = process_sp->GetMetaData(GetTraceUID(), thread_id, error.ref(),
+                                         buf, size, offset);
+    LLDB_LOG(log, "SBTrace::bytes_read - %" PRIx64, bytes_read);
+  }
+  return bytes_read;
+}
+
+void SBTrace::StopTrace(SBError &error, lldb::tid_t thread_id) {
+  ProcessSP process_sp(GetSP());
+  error.Clear();
+
+  if (!process_sp) {
+    error.SetErrorString("invalid process");
+    return;
+  }
+  process_sp->StopTrace(GetTraceUID(), thread_id, error.ref());
+}
+
+void SBTrace::GetTraceConfig(SBTraceOptions &options, SBError &error) {
+  ProcessSP process_sp(GetSP());
+  error.Clear();
+
+  if (!process_sp) {
+    error.SetErrorString("invalid process");
+  } else {
+    process_sp->GetTraceConfig(GetTraceUID(), error.ref(),
+                               options.m_traceoptions_sp);
+  }
+}
+
+lldb::user_id_t SBTrace::GetTraceUID() {
+  if (m_trace_impl_sp)
+    return m_trace_impl_sp->uid;
+  return LLDB_INVALID_UID;
+}
+
+void SBTrace::SetTraceUID(lldb::user_id_t uid) {
+  if (m_trace_impl_sp)
+    m_trace_impl_sp->uid = uid;
+}
+
+SBTrace::SBTrace() {
+  m_trace_impl_sp.reset(new 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; }
+
+bool SBTrace::IsValid() {
+  if (!m_trace_impl_sp)
+    return false;
+  if (!GetSP())
+    return false;
+  return true;
+}

source/API/SBTraceOptions.cpp

+//===-- SBTraceOptions.cpp --------------------------------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#include "lldb/API/SBTraceOptions.h"
+#include "lldb/API/SBError.h"
+#include "lldb/API/SBStructuredData.h"
+#include "lldb/Utility/Log.h"
+#include "lldb/Core/StructuredDataImpl.h"
+#include "lldb/Core/TraceOptions.h"
+
+using namespace lldb;
+using namespace lldb_private;
+
+SBTraceOptions::SBTraceOptions() {
+  m_traceoptions_sp.reset(new TraceOptions());
+}
+
+lldb::TraceType SBTraceOptions::getType() const {
+  if (m_traceoptions_sp)
+    return m_traceoptions_sp->getType();
+  return lldb::TraceType::eTraceTypeNone;
+}
+
+uint64_t SBTraceOptions::getTraceBufferSize() const {
+  if (m_traceoptions_sp)
+    return m_traceoptions_sp->getTraceBufferSize();
+  return 0;
+}
+
+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 structData;
+}
+
+uint64_t SBTraceOptions::getMetaDataBufferSize() const {
+  if (m_traceoptions_sp)
+    return m_traceoptions_sp->getTraceBufferSize();
+  return 0;
+}
+
+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) {
+  if (m_traceoptions_sp)
+    m_traceoptions_sp->setType(type);
+}
+
+void SBTraceOptions::setTraceBufferSize(uint64_t size) {
+  if (m_traceoptions_sp)
+    m_traceoptions_sp->setTraceBufferSize(size);
+}
+
+void SBTraceOptions::setMetaDataBufferSize(uint64_t size) {
+  if (m_traceoptions_sp)
+    m_traceoptions_sp->setMetaDataBufferSize(size);
+}
+
+bool SBTraceOptions::IsValid() {
+  if (m_traceoptions_sp)
+    return true;
+  return false;
+}
+
+void SBTraceOptions::setThreadID(lldb::tid_t thread_id) {
+  if (m_traceoptions_sp)
+    m_traceoptions_sp->setThreadID(thread_id);
+}
+
+lldb::tid_t SBTraceOptions::getThreadID() {
+  if (m_traceoptions_sp)
+    return m_traceoptions_sp->getThreadID();
+  return LLDB_INVALID_THREAD_ID;
+}