//===-- 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 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