| //===-- Trace.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_TARGET_TRACE_H |
| #define LLDB_TARGET_TRACE_H |
| |
| #include <optional> |
| #include <unordered_map> |
| |
| #include "llvm/Support/JSON.h" |
| |
| #include "lldb/Core/PluginInterface.h" |
| #include "lldb/Target/Thread.h" |
| #include "lldb/Target/TraceCursor.h" |
| #include "lldb/Utility/ArchSpec.h" |
| #include "lldb/Utility/TraceGDBRemotePackets.h" |
| #include "lldb/Utility/UnimplementedError.h" |
| #include "lldb/lldb-private.h" |
| #include "lldb/lldb-types.h" |
| |
| namespace lldb_private { |
| |
| /// \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: |
| /// 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. |
| virtual void Dump(Stream *s) const = 0; |
| |
| /// Save the trace to the specified directory, which will be created if |
| /// needed. This will also create a a file \a <directory>/trace.json with the |
| /// main properties of the trace session, along with others files which |
| /// contain the actual trace data. The trace.json file can be used later as |
| /// input for the "trace load" command to load the trace in LLDB. |
| /// |
| /// \param[in] directory |
| /// The directory where the trace files will be saved. |
| /// |
| /// \param[in] compact |
| /// Try not to save to disk information irrelevant to the traced processes. |
| /// Each trace plug-in implements this in a different fashion. |
| /// |
| /// \return |
| /// A \a FileSpec pointing to the bundle description file, or an \a |
| /// llvm::Error otherwise. |
| virtual llvm::Expected<FileSpec> SaveToDisk(FileSpec directory, |
| bool compact) = 0; |
| |
| /// Find a trace plug-in using JSON data. |
| /// |
| /// When loading trace data from disk, the information for the trace data |
| /// can be contained in multiple files and require plug-in specific |
| /// information about the CPU. Using data like JSON provides an |
| /// easy way to specify all of the settings and information that we will need |
| /// to load trace data into LLDB. This structured data can include: |
| /// - The plug-in name (this allows a specific plug-in to be selected) |
| /// - Architecture or target triple |
| /// - one or more paths to the trace data file on disk |
| /// - cpu trace data |
| /// - thread events or related information |
| /// - shared library load information to use for this trace data that |
| /// allows a target to be created so the trace information can be |
| /// symbolicated so that the trace information can be displayed to the |
| /// user |
| /// - shared library path |
| /// - load address |
| /// - information on how to fetch the shared library |
| /// - path to locally cached file on disk |
| /// - URL to download the file |
| /// - Any information needed to load the trace file |
| /// - CPU information |
| /// - Custom plug-in information needed to decode the trace information |
| /// correctly. |
| /// |
| /// \param[in] debugger |
| /// The debugger instance where new Targets will be created as part of the |
| /// JSON data parsing. |
| /// |
| /// \param[in] bundle_description |
| /// The trace bundle description object describing the trace session. |
| /// |
| /// \param[in] bundle_dir |
| /// The path to the directory that contains the trace bundle. |
| static llvm::Expected<lldb::TraceSP> |
| FindPluginForPostMortemProcess(Debugger &debugger, |
| const llvm::json::Value &bundle_description, |
| llvm::StringRef session_file_dir); |
| |
| /// Find a trace plug-in to trace a live process. |
| /// |
| /// \param[in] plugin_name |
| /// Plug-in name to search. |
| /// |
| /// \param[in] process |
| /// Live process to trace. |
| /// |
| /// \return |
| /// A \a TraceSP instance, or an \a llvm::Error if the plug-in name |
| /// doesn't match any registered plug-ins or tracing couldn't be |
| /// started. |
| static llvm::Expected<lldb::TraceSP> |
| FindPluginForLiveProcess(llvm::StringRef plugin_name, Process &process); |
| |
| /// Get the schema of a Trace plug-in given its name. |
| /// |
| /// \param[in] plugin_name |
| /// Name of the trace plugin. |
| static llvm::Expected<llvm::StringRef> |
| FindPluginSchema(llvm::StringRef plugin_name); |
| |
| /// Load a trace from a trace description file and create Targets, |
| /// Processes and Threads based on the contents of such file. |
| /// |
| /// \param[in] debugger |
| /// The debugger instance where new Targets will be created as part of the |
| /// JSON data parsing. |
| /// |
| /// \param[in] trace_description_file |
| /// The file containing the necessary information to load the trace. |
| /// |
| /// \return |
| /// A \a TraceSP instance, or an \a llvm::Error if loading the trace |
| /// fails. |
| static llvm::Expected<lldb::TraceSP> |
| LoadPostMortemTraceFromFile(Debugger &debugger, |
| const FileSpec &trace_description_file); |
| |
| /// Get the command handle for the "process trace start" command. |
| virtual lldb::CommandObjectSP |
| GetProcessTraceStartCommand(CommandInterpreter &interpreter) = 0; |
| |
| /// Get the command handle for the "thread trace start" command. |
| virtual lldb::CommandObjectSP |
| GetThreadTraceStartCommand(CommandInterpreter &interpreter) = 0; |
| |
| /// \return |
| /// The JSON schema of this Trace plug-in. |
| virtual llvm::StringRef GetSchema() = 0; |
| |
| /// Get a \a TraceCursor for the given thread's trace. |
| /// |
| /// \return |
| /// A \a TraceCursorSP. If the thread is not traced or its trace |
| /// information failed to load, an \a llvm::Error is returned. |
| virtual llvm::Expected<lldb::TraceCursorSP> |
| CreateNewCursor(Thread &thread) = 0; |
| |
| /// Dump general info about a given thread's trace. Each Trace plug-in |
| /// decides which data to show. |
| /// |
| /// \param[in] thread |
| /// The thread that owns the trace in question. |
| /// |
| /// \param[in] s |
| /// The stream object where the info will be printed printed. |
| /// |
| /// \param[in] verbose |
| /// If \b true, print detailed info |
| /// If \b false, print compact info |
| virtual void DumpTraceInfo(Thread &thread, Stream &s, bool verbose, |
| bool json) = 0; |
| |
| /// Check if a thread is currently traced by this object. |
| /// |
| /// \param[in] tid |
| /// The id of the thread in question. |
| /// |
| /// \return |
| /// \b true if the thread is traced by this instance, \b false otherwise. |
| virtual bool IsTraced(lldb::tid_t tid) = 0; |
| |
| /// \return |
| /// A description of the parameters to use for the \a Trace::Start method. |
| virtual const char *GetStartConfigurationHelp() = 0; |
| |
| /// Start tracing a live process. |
| /// |
| /// \param[in] configuration |
| /// See \a SBTrace::Start(const lldb::SBStructuredData &) for more |
| /// information. |
| /// |
| /// \return |
| /// \a llvm::Error::success if the operation was successful, or |
| /// \a llvm::Error otherwise. |
| virtual llvm::Error Start( |
| 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::Start(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 Start( |
| llvm::ArrayRef<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. |
| llvm::Error Stop(llvm::ArrayRef<lldb::tid_t> tids); |
| |
| /// Stop tracing all current and future threads of a live process. |
| /// |
| /// \param[in] request |
| /// The information determining which threads or process to stop tracing. |
| /// |
| /// \return |
| /// \a llvm::Error::success if the operation was successful, or |
| /// \a llvm::Error otherwise. |
| llvm::Error Stop(); |
| |
| /// \return |
| /// The stop ID of the live process being traced, or an invalid stop ID |
| /// if the trace is in an error or invalid state. |
| uint32_t GetStopID(); |
| |
| using OnBinaryDataReadCallback = |
| std::function<llvm::Error(llvm::ArrayRef<uint8_t> data)>; |
| using OnCpusBinaryDataReadCallback = std::function<llvm::Error( |
| const llvm::DenseMap<lldb::cpu_id_t, llvm::ArrayRef<uint8_t>> |
| &cpu_to_data)>; |
| |
| /// Fetch binary data associated with a thread, either live or postmortem, and |
| /// pass it to the given callback. The reason of having a callback is to free |
| /// the caller from having to manage the life cycle of the data and to hide |
| /// the different data fetching procedures that exist for live and post mortem |
| /// threads. |
| /// |
| /// The fetched data is not persisted after the callback is invoked. |
| /// |
| /// \param[in] tid |
| /// The tid who owns the data. |
| /// |
| /// \param[in] kind |
| /// The kind of data to read. |
| /// |
| /// \param[in] callback |
| /// The callback to be invoked once the data was successfully read. Its |
| /// return value, which is an \a llvm::Error, is returned by this |
| /// function. |
| /// |
| /// \return |
| /// An \a llvm::Error if the data couldn't be fetched, or the return value |
| /// of the callback, otherwise. |
| llvm::Error OnThreadBinaryDataRead(lldb::tid_t tid, llvm::StringRef kind, |
| OnBinaryDataReadCallback callback); |
| |
| /// Fetch binary data associated with a cpu, either live or postmortem, and |
| /// pass it to the given callback. The reason of having a callback is to free |
| /// the caller from having to manage the life cycle of the data and to hide |
| /// the different data fetching procedures that exist for live and post mortem |
| /// cpus. |
| /// |
| /// The fetched data is not persisted after the callback is invoked. |
| /// |
| /// \param[in] cpu_id |
| /// The cpu who owns the data. |
| /// |
| /// \param[in] kind |
| /// The kind of data to read. |
| /// |
| /// \param[in] callback |
| /// The callback to be invoked once the data was successfully read. Its |
| /// return value, which is an \a llvm::Error, is returned by this |
| /// function. |
| /// |
| /// \return |
| /// An \a llvm::Error if the data couldn't be fetched, or the return value |
| /// of the callback, otherwise. |
| llvm::Error OnCpuBinaryDataRead(lldb::cpu_id_t cpu_id, llvm::StringRef kind, |
| OnBinaryDataReadCallback callback); |
| |
| /// Similar to \a OnCpuBinaryDataRead but this is able to fetch the same data |
| /// from all cpus at once. |
| llvm::Error OnAllCpusBinaryDataRead(llvm::StringRef kind, |
| OnCpusBinaryDataReadCallback callback); |
| |
| /// \return |
| /// All the currently traced processes. |
| std::vector<Process *> GetAllProcesses(); |
| |
| /// \return |
| /// The list of cpus being traced. Might be empty depending on the |
| /// plugin. |
| llvm::ArrayRef<lldb::cpu_id_t> GetTracedCpus(); |
| |
| /// Helper method for reading a data file and passing its data to the given |
| /// callback. |
| static llvm::Error OnDataFileRead(FileSpec file, |
| OnBinaryDataReadCallback callback); |
| |
| protected: |
| /// Get the currently traced live process. |
| /// |
| /// \return |
| /// If it's not a live process, return \a nullptr. |
| Process *GetLiveProcess(); |
| |
| /// Get the currently traced postmortem processes. |
| /// |
| /// \return |
| /// If it's not a live process session, return an empty list. |
| llvm::ArrayRef<Process *> GetPostMortemProcesses(); |
| |
| /// Dispatcher for live trace data requests with some additional error |
| /// checking. |
| llvm::Expected<std::vector<uint8_t>> |
| GetLiveTraceBinaryData(const TraceGetBinaryDataRequest &request, |
| uint64_t expected_size); |
| |
| /// Implementation of \a OnThreadBinaryDataRead() for live threads. |
| llvm::Error OnLiveThreadBinaryDataRead(lldb::tid_t tid, llvm::StringRef kind, |
| OnBinaryDataReadCallback callback); |
| |
| /// Implementation of \a OnLiveBinaryDataRead() for live cpus. |
| llvm::Error OnLiveCpuBinaryDataRead(lldb::cpu_id_t cpu, llvm::StringRef kind, |
| OnBinaryDataReadCallback callback); |
| |
| /// Implementation of \a OnThreadBinaryDataRead() for post mortem threads. |
| llvm::Error |
| OnPostMortemThreadBinaryDataRead(lldb::tid_t tid, llvm::StringRef kind, |
| OnBinaryDataReadCallback callback); |
| |
| /// Implementation of \a OnCpuBinaryDataRead() for post mortem cpus. |
| llvm::Error OnPostMortemCpuBinaryDataRead(lldb::cpu_id_t cpu_id, |
| llvm::StringRef kind, |
| OnBinaryDataReadCallback callback); |
| |
| /// Get the file path containing data of a postmortem thread given a data |
| /// identifier. |
| /// |
| /// \param[in] tid |
| /// The thread whose data is requested. |
| /// |
| /// \param[in] kind |
| /// The kind of data requested. |
| /// |
| /// \return |
| /// The file spec containing the requested data, or an \a llvm::Error in |
| /// case of failures. |
| llvm::Expected<FileSpec> GetPostMortemThreadDataFile(lldb::tid_t tid, |
| llvm::StringRef kind); |
| |
| /// Get the file path containing data of a postmortem cpu given a data |
| /// identifier. |
| /// |
| /// \param[in] cpu_id |
| /// The cpu whose data is requested. |
| /// |
| /// \param[in] kind |
| /// The kind of data requested. |
| /// |
| /// \return |
| /// The file spec containing the requested data, or an \a llvm::Error in |
| /// case of failures. |
| llvm::Expected<FileSpec> GetPostMortemCpuDataFile(lldb::cpu_id_t cpu_id, |
| llvm::StringRef kind); |
| |
| /// Associate a given thread with a data file using a data identifier. |
| /// |
| /// \param[in] tid |
| /// The thread associated with the data file. |
| /// |
| /// \param[in] kind |
| /// The kind of data being registered. |
| /// |
| /// \param[in] file_spec |
| /// The path of the data file. |
| void SetPostMortemThreadDataFile(lldb::tid_t tid, llvm::StringRef kind, |
| FileSpec file_spec); |
| |
| /// Associate a given cpu with a data file using a data identifier. |
| /// |
| /// \param[in] cpu_id |
| /// The cpu associated with the data file. |
| /// |
| /// \param[in] kind |
| /// The kind of data being registered. |
| /// |
| /// \param[in] file_spec |
| /// The path of the data file. |
| void SetPostMortemCpuDataFile(lldb::cpu_id_t cpu_id, llvm::StringRef kind, |
| FileSpec file_spec); |
| |
| /// Get binary data of a live thread given a data identifier. |
| /// |
| /// \param[in] tid |
| /// The thread whose data is requested. |
| /// |
| /// \param[in] kind |
| /// The kind of data requested. |
| /// |
| /// \return |
| /// A vector of bytes with the requested data, or an \a llvm::Error in |
| /// case of failures. |
| llvm::Expected<std::vector<uint8_t>> |
| GetLiveThreadBinaryData(lldb::tid_t tid, llvm::StringRef kind); |
| |
| /// Get binary data of a live cpu given a data identifier. |
| /// |
| /// \param[in] cpu_id |
| /// The cpu whose data is requested. |
| /// |
| /// \param[in] kind |
| /// The kind of data requested. |
| /// |
| /// \return |
| /// A vector of bytes with the requested data, or an \a llvm::Error in |
| /// case of failures. |
| llvm::Expected<std::vector<uint8_t>> |
| GetLiveCpuBinaryData(lldb::cpu_id_t cpu_id, llvm::StringRef kind); |
| |
| /// Get binary data of the current process given a data identifier. |
| /// |
| /// \param[in] kind |
| /// The kind of data requested. |
| /// |
| /// \return |
| /// A vector of bytes with the requested data, or an \a llvm::Error in |
| /// case of failures. |
| llvm::Expected<std::vector<uint8_t>> |
| GetLiveProcessBinaryData(llvm::StringRef kind); |
| |
| /// Get the size of the data returned by \a GetLiveThreadBinaryData |
| std::optional<uint64_t> GetLiveThreadBinaryDataSize(lldb::tid_t tid, |
| llvm::StringRef kind); |
| |
| /// Get the size of the data returned by \a GetLiveCpuBinaryData |
| std::optional<uint64_t> GetLiveCpuBinaryDataSize(lldb::cpu_id_t cpu_id, |
| llvm::StringRef kind); |
| |
| /// Get the size of the data returned by \a GetLiveProcessBinaryData |
| std::optional<uint64_t> GetLiveProcessBinaryDataSize(llvm::StringRef kind); |
| |
| /// Constructor for post mortem processes |
| Trace(llvm::ArrayRef<lldb::ProcessSP> postmortem_processes, |
| std::optional<std::vector<lldb::cpu_id_t>> postmortem_cpus); |
| |
| /// Constructor for a live process |
| Trace(Process &live_process) : m_live_process(&live_process) {} |
| |
| /// Start tracing a live process or its threads. |
| /// |
| /// \param[in] request |
| /// JSON object with the information necessary to start tracing. In the |
| /// case of gdb-remote processes, this JSON object should conform to the |
| /// jLLDBTraceStart packet. |
| /// |
| /// \return |
| /// \a llvm::Error::success if the operation was successful, or |
| /// \a llvm::Error otherwise. |
| llvm::Error Start(const llvm::json::Value &request); |
| |
| /// Get the current tracing state of a live process and its threads. |
| /// |
| /// \return |
| /// A JSON object string with custom data depending on the trace |
| /// technology, or an \a llvm::Error in case of errors. |
| llvm::Expected<std::string> GetLiveProcessState(); |
| |
| /// Method to be overriden by the plug-in to refresh its own state. |
| /// |
| /// This is invoked by RefreshLiveProcessState when a new state is found. |
| /// |
| /// \param[in] state |
| /// The jLLDBTraceGetState response. |
| /// |
| /// \param[in] json_response |
| /// The original JSON response as a string. It might be useful to redecode |
| /// it if it contains custom data for a specific trace plug-in. |
| /// |
| /// \return |
| /// \b Error::success() if this operation succeedes, or an actual error |
| /// otherwise. |
| virtual llvm::Error |
| DoRefreshLiveProcessState(TraceGetStateResponse state, |
| llvm::StringRef json_response) = 0; |
| |
| /// Return the list of processes traced by this instance. None of the returned |
| /// pointers are invalid. |
| std::vector<Process *> GetTracedProcesses(); |
| |
| /// Method to be invoked by the plug-in to refresh the live process state. It |
| /// will invoked DoRefreshLiveProcessState at some point, which should be |
| /// implemented by the plug-in for custom state handling. |
| /// |
| /// The result is cached through the same process stop. Even in the case of |
| /// errors, it caches the error. |
| /// |
| /// \return |
| /// An error message if this operation failed, or \b nullptr otherwise. |
| const char *RefreshLiveProcessState(); |
| |
| private: |
| uint32_t m_stop_id = LLDB_INVALID_STOP_ID; |
| |
| /// Process traced by this object if doing live tracing. Otherwise it's null. |
| Process *m_live_process = nullptr; |
| |
| /// We package all the data that can change upon process stops to make sure |
| /// this contract is very visible. |
| /// This variable should only be accessed directly by constructores or live |
| /// process data refreshers. |
| struct Storage { |
| /// Portmortem processes traced by this object if doing non-live tracing. |
| /// Otherwise it's empty. |
| std::vector<Process *> postmortem_processes; |
| |
| /// These data kinds are returned by lldb-server when fetching the state of |
| /// the tracing session. The size in bytes can be used later for fetching |
| /// the data in batches. |
| /// \{ |
| |
| /// tid -> data kind -> size |
| llvm::DenseMap<lldb::tid_t, llvm::DenseMap<ConstString, uint64_t>> |
| live_thread_data; |
| |
| /// cpu id -> data kind -> size |
| llvm::DenseMap<lldb::cpu_id_t, llvm::DenseMap<ConstString, uint64_t>> |
| live_cpu_data_sizes; |
| /// cpu id -> data kind -> bytes |
| llvm::DenseMap<lldb::cpu_id_t, |
| llvm::DenseMap<ConstString, std::vector<uint8_t>>> |
| live_cpu_data; |
| |
| /// data kind -> size |
| llvm::DenseMap<ConstString, uint64_t> live_process_data; |
| /// \} |
| |
| /// The list of cpus being traced. Might be \b std::nullopt depending on the |
| /// plug-in. |
| std::optional<std::vector<lldb::cpu_id_t>> cpus; |
| |
| /// Postmortem traces can specific additional data files, which are |
| /// represented in this variable using a data kind identifier for each file. |
| /// \{ |
| |
| /// tid -> data kind -> file |
| llvm::DenseMap<lldb::tid_t, llvm::DenseMap<ConstString, FileSpec>> |
| postmortem_thread_data; |
| |
| /// cpu id -> data kind -> file |
| llvm::DenseMap<lldb::cpu_id_t, llvm::DenseMap<ConstString, FileSpec>> |
| postmortem_cpu_data; |
| |
| /// \} |
| |
| std::optional<std::string> live_refresh_error; |
| } m_storage; |
| |
| /// Get the storage after refreshing the data in the case of a live process. |
| Storage &GetUpdatedStorage(); |
| }; |
| |
| } // namespace lldb_private |
| |
| #endif // LLDB_TARGET_TRACE_H |