1 //===-- SBTrace.h -----------------------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLDB_SBTrace_h_ 10 #define LLDB_SBTrace_h_ 11 12 #include "lldb/API/SBDefines.h" 13 #include "lldb/API/SBError.h" 14 15 class TraceImpl; 16 17 namespace lldb { 18 19 class LLDB_API SBTrace { 20 public: 21 SBTrace(); 22 /// Obtain the trace data as raw bytes. 23 /// 24 /// \param[out] error 25 /// An error explaining what went wrong. 26 /// 27 /// \param[in] buf 28 /// Buffer to write the trace data to. 29 /// 30 /// \param[in] size 31 /// The size of the buffer used to read the data. This is 32 /// also the size of the data intended to read. It is also 33 /// possible to partially read the trace data for some trace 34 /// technologies by specifying a smaller buffer. 35 /// 36 /// \param[in] offset 37 /// The start offset to begin reading the trace data. 38 /// 39 /// \param[in] thread_id 40 /// Tracing could be started for the complete process or a 41 /// single thread, in the first case the traceid obtained would 42 /// map to all the threads existing within the process and the 43 /// ones spawning later. The thread_id parameter can be used in 44 /// such a scenario to select the trace data for a specific 45 /// thread. 46 /// 47 /// \return 48 /// The size of the trace data effectively read by the API call. 49 size_t GetTraceData(SBError &error, void *buf, size_t size, size_t offset = 0, 50 lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID); 51 52 /// Obtain any meta data as raw bytes for the tracing instance. 53 /// The input parameter definition is similar to the previous 54 /// function. 55 size_t GetMetaData(SBError &error, void *buf, size_t size, size_t offset = 0, 56 lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID); 57 58 /// Stop the tracing instance. Stopping the trace will also 59 /// lead to deletion of any gathered trace data. 60 /// 61 /// \param[out] error 62 /// An error explaining what went wrong. 63 /// 64 /// \param[in] thread_id 65 /// The trace id could map to a tracing instance for a thread 66 /// or could also map to a group of threads being traced with 67 /// the same trace options. A thread_id is normally optional 68 /// except in the case of tracing a complete process and tracing 69 /// needs to switched off on a particular thread. 70 /// A situation could occur where initially a thread (lets say 71 /// thread A) is being individually traced with a particular 72 /// trace id and then tracing is started on the complete 73 /// process, in this case thread A will continue without any 74 /// change. All newly spawned threads would be traced with the 75 /// trace id of the process. 76 /// Now if the StopTrace API is called for the whole process, 77 /// thread A will not be stopped and must be stopped separately. 78 void StopTrace(SBError &error, 79 lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID); 80 81 /// Get the trace configuration being used for the trace instance. 82 /// The threadid in the SBTraceOptions needs to be set when the 83 /// configuration used by a specific thread is being requested. 84 /// 85 /// \param[out] options 86 /// The trace options actually used by the trace instance 87 /// would be filled by the API. 88 /// 89 /// \param[out] error 90 /// An error explaining what went wrong. 91 void GetTraceConfig(SBTraceOptions &options, SBError &error); 92 93 lldb::user_id_t GetTraceUID(); 94 95 explicit operator bool() const; 96 97 bool IsValid(); 98 99 protected: 100 typedef std::shared_ptr<TraceImpl> TraceImplSP; 101 102 friend class SBProcess; 103 104 void SetTraceUID(lldb::user_id_t uid); 105 106 TraceImplSP m_trace_impl_sp; 107 108 lldb::ProcessSP GetSP() const; 109 110 void SetSP(const ProcessSP &process_sp); 111 112 lldb::ProcessWP m_opaque_wp; 113 }; 114 } // namespace lldb 115 116 #endif // LLDB_SBTrace_h_ 117