8b3af63b89
A lot of comments in LLDB are surrounded by an ASCII line to delimit the begging and end of the comment. Its use is not really consistent across the code base, sometimes the lines are longer, sometimes they are shorter and sometimes they are omitted. Furthermore, it looks kind of weird with the 80 column limit, where the comment actually extends past the line, but not by much. Furthermore, when /// is used for Doxygen comments, it looks particularly odd. And when // is used, it incorrectly gives the impression that it's actually a Doxygen comment. I assume these lines were added to improve distinguishing between comments and code. However, given that todays editors and IDEs do a great job at highlighting comments, I think it's worth to drop this for the sake of consistency. The alternative is fixing all the inconsistencies, which would create a lot more churn. Differential revision: https://reviews.llvm.org/D60508 llvm-svn: 358135
416 lines
14 KiB
C++
416 lines
14 KiB
C++
//===-- SBProcess.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_SBProcess_h_
|
|
#define LLDB_SBProcess_h_
|
|
|
|
#include "lldb/API/SBDefines.h"
|
|
#include "lldb/API/SBError.h"
|
|
#include "lldb/API/SBProcessInfo.h"
|
|
#include "lldb/API/SBQueue.h"
|
|
#include "lldb/API/SBTarget.h"
|
|
#include <stdio.h>
|
|
|
|
namespace lldb {
|
|
|
|
class SBEvent;
|
|
|
|
class LLDB_API SBProcess {
|
|
public:
|
|
/// Broadcaster event bits definitions.
|
|
FLAGS_ANONYMOUS_ENUM(){eBroadcastBitStateChanged = (1 << 0),
|
|
eBroadcastBitInterrupt = (1 << 1),
|
|
eBroadcastBitSTDOUT = (1 << 2),
|
|
eBroadcastBitSTDERR = (1 << 3),
|
|
eBroadcastBitProfileData = (1 << 4),
|
|
eBroadcastBitStructuredData = (1 << 5)};
|
|
|
|
SBProcess();
|
|
|
|
SBProcess(const lldb::SBProcess &rhs);
|
|
|
|
const lldb::SBProcess &operator=(const lldb::SBProcess &rhs);
|
|
|
|
SBProcess(const lldb::ProcessSP &process_sp);
|
|
|
|
~SBProcess();
|
|
|
|
static const char *GetBroadcasterClassName();
|
|
|
|
const char *GetPluginName();
|
|
|
|
// DEPRECATED: use GetPluginName()
|
|
const char *GetShortPluginName();
|
|
|
|
void Clear();
|
|
|
|
explicit operator bool() const;
|
|
|
|
bool IsValid() const;
|
|
|
|
lldb::SBTarget GetTarget() const;
|
|
|
|
lldb::ByteOrder GetByteOrder() const;
|
|
|
|
size_t PutSTDIN(const char *src, size_t src_len);
|
|
|
|
size_t GetSTDOUT(char *dst, size_t dst_len) const;
|
|
|
|
size_t GetSTDERR(char *dst, size_t dst_len) const;
|
|
|
|
size_t GetAsyncProfileData(char *dst, size_t dst_len) const;
|
|
|
|
void ReportEventState(const lldb::SBEvent &event, FILE *out) const;
|
|
|
|
void AppendEventStateReport(const lldb::SBEvent &event,
|
|
lldb::SBCommandReturnObject &result);
|
|
|
|
/// Remote connection related functions. These will fail if the
|
|
/// process is not in eStateConnected. They are intended for use
|
|
/// when connecting to an externally managed debugserver instance.
|
|
bool RemoteAttachToProcessWithID(lldb::pid_t pid, lldb::SBError &error);
|
|
|
|
bool RemoteLaunch(char const **argv, char const **envp,
|
|
const char *stdin_path, const char *stdout_path,
|
|
const char *stderr_path, const char *working_directory,
|
|
uint32_t launch_flags, bool stop_at_entry,
|
|
lldb::SBError &error);
|
|
|
|
// Thread related functions
|
|
uint32_t GetNumThreads();
|
|
|
|
lldb::SBThread GetThreadAtIndex(size_t index);
|
|
|
|
lldb::SBThread GetThreadByID(lldb::tid_t sb_thread_id);
|
|
|
|
lldb::SBThread GetThreadByIndexID(uint32_t index_id);
|
|
|
|
lldb::SBThread GetSelectedThread() const;
|
|
|
|
// Function for lazily creating a thread using the current OS plug-in. This
|
|
// function will be removed in the future when there are APIs to create
|
|
// SBThread objects through the interface and add them to the process through
|
|
// the SBProcess API.
|
|
lldb::SBThread CreateOSPluginThread(lldb::tid_t tid, lldb::addr_t context);
|
|
|
|
bool SetSelectedThread(const lldb::SBThread &thread);
|
|
|
|
bool SetSelectedThreadByID(lldb::tid_t tid);
|
|
|
|
bool SetSelectedThreadByIndexID(uint32_t index_id);
|
|
|
|
// Queue related functions
|
|
uint32_t GetNumQueues();
|
|
|
|
lldb::SBQueue GetQueueAtIndex(size_t index);
|
|
|
|
// Stepping related functions
|
|
|
|
lldb::StateType GetState();
|
|
|
|
int GetExitStatus();
|
|
|
|
const char *GetExitDescription();
|
|
|
|
/// Gets the process ID
|
|
///
|
|
/// Returns the process identifier for the process as it is known
|
|
/// on the system on which the process is running. For unix systems
|
|
/// this is typically the same as if you called "getpid()" in the
|
|
/// process.
|
|
///
|
|
/// \return
|
|
/// Returns LLDB_INVALID_PROCESS_ID if this object does not
|
|
/// contain a valid process object, or if the process has not
|
|
/// been launched. Returns a valid process ID if the process is
|
|
/// valid.
|
|
lldb::pid_t GetProcessID();
|
|
|
|
/// Gets the unique ID associated with this process object
|
|
///
|
|
/// Unique IDs start at 1 and increment up with each new process
|
|
/// instance. Since starting a process on a system might always
|
|
/// create a process with the same process ID, there needs to be a
|
|
/// way to tell two process instances apart.
|
|
///
|
|
/// \return
|
|
/// Returns a non-zero integer ID if this object contains a
|
|
/// valid process object, zero if this object does not contain
|
|
/// a valid process object.
|
|
uint32_t GetUniqueID();
|
|
|
|
uint32_t GetAddressByteSize() const;
|
|
|
|
lldb::SBError Destroy();
|
|
|
|
lldb::SBError Continue();
|
|
|
|
lldb::SBError Stop();
|
|
|
|
lldb::SBError Kill();
|
|
|
|
lldb::SBError Detach();
|
|
|
|
lldb::SBError Detach(bool keep_stopped);
|
|
|
|
lldb::SBError Signal(int signal);
|
|
|
|
lldb::SBUnixSignals GetUnixSignals();
|
|
|
|
void SendAsyncInterrupt();
|
|
|
|
uint32_t GetStopID(bool include_expression_stops = false);
|
|
|
|
/// Gets the stop event corresponding to stop ID.
|
|
//
|
|
/// Note that it wasn't fully implemented and tracks only the stop
|
|
/// event for the last natural stop ID.
|
|
///
|
|
/// \param [in] stop_id
|
|
/// The ID of the stop event to return.
|
|
///
|
|
/// \return
|
|
/// The stop event corresponding to stop ID.
|
|
lldb::SBEvent GetStopEventForStopID(uint32_t stop_id);
|
|
|
|
size_t ReadMemory(addr_t addr, void *buf, size_t size, lldb::SBError &error);
|
|
|
|
size_t WriteMemory(addr_t addr, const void *buf, size_t size,
|
|
lldb::SBError &error);
|
|
|
|
size_t ReadCStringFromMemory(addr_t addr, void *buf, size_t size,
|
|
lldb::SBError &error);
|
|
|
|
uint64_t ReadUnsignedFromMemory(addr_t addr, uint32_t byte_size,
|
|
lldb::SBError &error);
|
|
|
|
lldb::addr_t ReadPointerFromMemory(addr_t addr, lldb::SBError &error);
|
|
|
|
// Events
|
|
static lldb::StateType GetStateFromEvent(const lldb::SBEvent &event);
|
|
|
|
static bool GetRestartedFromEvent(const lldb::SBEvent &event);
|
|
|
|
static size_t GetNumRestartedReasonsFromEvent(const lldb::SBEvent &event);
|
|
|
|
static const char *
|
|
GetRestartedReasonAtIndexFromEvent(const lldb::SBEvent &event, size_t idx);
|
|
|
|
static lldb::SBProcess GetProcessFromEvent(const lldb::SBEvent &event);
|
|
|
|
static bool GetInterruptedFromEvent(const lldb::SBEvent &event);
|
|
|
|
static lldb::SBStructuredData
|
|
GetStructuredDataFromEvent(const lldb::SBEvent &event);
|
|
|
|
static bool EventIsProcessEvent(const lldb::SBEvent &event);
|
|
|
|
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);
|
|
|
|
/// Load a shared library into this process, starting with a
|
|
/// library name and a list of paths, searching along the list of
|
|
/// paths till you find a matching library.
|
|
///
|
|
/// \param[in] image_spec
|
|
/// The name of the shared library that you want to load.
|
|
/// If image_spec is a relative path, the relative path will be
|
|
/// appended to the search paths.
|
|
/// If the image_spec is an absolute path, just the basename is used.
|
|
///
|
|
/// \param[in] paths
|
|
/// A list of paths to search for the library whose basename is
|
|
/// local_spec.
|
|
///
|
|
/// \param[out] loaded_path
|
|
/// If the library was found along the paths, this will store the
|
|
/// full path to the found library.
|
|
///
|
|
/// \param[out] error
|
|
/// An error object that gets filled in with any errors that
|
|
/// might occur when trying to search for the shared library.
|
|
///
|
|
/// \return
|
|
/// A token that represents the shared library that can be
|
|
/// later passed to UnloadImage. A value of
|
|
/// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
|
|
/// library can't be opened.
|
|
uint32_t LoadImageUsingPaths(const lldb::SBFileSpec &image_spec,
|
|
SBStringList &paths,
|
|
lldb::SBFileSpec &loaded_path,
|
|
lldb::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.
|
|
///
|
|
/// When the process is stopped and you have an SBThread, lldb may be
|
|
/// able to show a backtrace of when that thread was originally created,
|
|
/// or the work item was enqueued to it (in the case of a libdispatch
|
|
/// queue).
|
|
///
|
|
/// \return
|
|
/// The number of thread-origin extended backtrace types that may be
|
|
/// available.
|
|
uint32_t GetNumExtendedBacktraceTypes();
|
|
|
|
/// 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);
|
|
|
|
bool IsInstrumentationRuntimePresent(InstrumentationRuntimeType type);
|
|
|
|
/// Save the state of the process in a core file (or mini dump on Windows).
|
|
lldb::SBError SaveCore(const char *file_name);
|
|
|
|
/// Query the address load_addr and store the details of the memory
|
|
/// region that contains it in the supplied SBMemoryRegionInfo object.
|
|
/// To iterate over all memory regions use GetMemoryRegionList.
|
|
///
|
|
/// \param[in] load_addr
|
|
/// The address to be queried.
|
|
///
|
|
/// \param[out] region_info
|
|
/// A reference to an SBMemoryRegionInfo object that will contain
|
|
/// the details of the memory region containing load_addr.
|
|
///
|
|
/// \return
|
|
/// An error object describes any errors that occurred while
|
|
/// querying load_addr.
|
|
lldb::SBError GetMemoryRegionInfo(lldb::addr_t load_addr,
|
|
lldb::SBMemoryRegionInfo ®ion_info);
|
|
|
|
/// Return the list of memory regions within the process.
|
|
///
|
|
/// \return
|
|
/// A list of all witin the process memory regions.
|
|
lldb::SBMemoryRegionInfoList GetMemoryRegions();
|
|
|
|
/// Return information about the process.
|
|
///
|
|
/// Valid process info will only be returned when the process is
|
|
/// alive, use SBProcessInfo::IsValid() to check returned info is
|
|
/// valid.
|
|
lldb::SBProcessInfo GetProcessInfo();
|
|
|
|
protected:
|
|
friend class SBAddress;
|
|
friend class SBBreakpoint;
|
|
friend class SBBreakpointLocation;
|
|
friend class SBCommandInterpreter;
|
|
friend class SBDebugger;
|
|
friend class SBExecutionContext;
|
|
friend class SBFunction;
|
|
friend class SBModule;
|
|
friend class SBTarget;
|
|
friend class SBThread;
|
|
friend class SBValue;
|
|
friend class lldb_private::QueueImpl;
|
|
|
|
lldb::ProcessSP GetSP() const;
|
|
|
|
void SetSP(const lldb::ProcessSP &process_sp);
|
|
|
|
lldb::ProcessWP m_opaque_wp;
|
|
};
|
|
|
|
} // namespace lldb
|
|
|
|
#endif // LLDB_SBProcess_h_
|