lldb_controller.h

Go to the documentation of this file.

 
#pragma once
 
#include <lldb/API/LLDB.h>
 
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <string>
#include <vector>
 
// Windows doesn't define pid_t, use LLDB's definition
#ifdef _WIN32
using pid_t = lldb::pid_t;
#endif
 
namespace ascii_query {
 
enum class ProcessState {
  Invalid,  
  Running,  
  Stopped,  
  Exited,   
  Crashed,  
  Detached, 
};
 
struct ThreadInfo {
  uint64_t id;             
  uint32_t index;          
  std::string name;        
  std::string stop_reason; 
  std::string function;    
  std::string file;        
  uint32_t line;           
  bool is_selected;        
};
 
struct FrameInfo {
  uint32_t index;       
  std::string function; 
  std::string file;     
  uint32_t line;        
  uint64_t pc;          
  uint64_t fp;          
};
 
struct VariableInfo {
  std::string name;    
  std::string type;    
  std::string value;   
  std::string summary; 
  uint64_t address;    
  size_t size;         
  bool is_valid;       
  bool is_pointer;     
  bool is_aggregate;   
 
  std::vector<VariableInfo> children; 
};
 
struct BreakpointInfo {
  int32_t id;            
  std::string file;      
  uint32_t line;         
  std::string condition; 
  uint32_t hit_count;    
  bool enabled;          
  bool resolved;         
};
 
class LLDBController {
public:
  LLDBController();
  ~LLDBController();
 
  // Non-copyable, non-movable (owns LLDB resources)
  LLDBController(const LLDBController &) = delete;
  LLDBController &operator=(const LLDBController &) = delete;
  LLDBController(LLDBController &&) = delete;
  LLDBController &operator=(LLDBController &&) = delete;
 
  // =========================================================================
  // Initialization
  // =========================================================================
 
  bool initialize();
 
  void shutdown();
 
  // =========================================================================
  // Process Attachment
  // =========================================================================
 
  bool attach(pid_t pid);
 
  bool attachByName(const std::string &process_name, bool wait_for = false);
 
  void detach();
 
  [[nodiscard]] bool isAttached() const;
 
  [[nodiscard]] pid_t targetPid() const;
 
  [[nodiscard]] std::string targetName() const;
 
  // =========================================================================
  // Process Control
  // =========================================================================
 
  bool stop();
 
  bool resume();
 
  bool stepInto();
 
  bool stepOver();
 
  bool stepOut();
 
  [[nodiscard]] ProcessState state() const;
 
  [[nodiscard]] const std::string &lastError() const;
 
  // =========================================================================
  // Thread Information
  // =========================================================================
 
  [[nodiscard]] std::vector<ThreadInfo> getThreads() const;
 
  [[nodiscard]] std::optional<ThreadInfo> getSelectedThread() const;
 
  bool selectThread(uint64_t thread_id);
 
  // =========================================================================
  // Stack Frames
  // =========================================================================
 
  [[nodiscard]] std::vector<FrameInfo> getFrames(uint32_t max_frames = 0) const;
 
  [[nodiscard]] std::optional<FrameInfo> getFrame(uint32_t frame_index) const;
 
  // =========================================================================
  // Variable Reading
  // =========================================================================
 
  [[nodiscard]] std::optional<VariableInfo> readVariable(const std::string &name, uint32_t frame_index = 0,
                                                         uint32_t expand_depth = 0) const;
 
  [[nodiscard]] std::vector<VariableInfo> listVariables(uint32_t frame_index = 0, bool include_args = true,
                                                        bool include_locals = true, bool include_statics = false) const;
 
  // =========================================================================
  // Breakpoints
  // =========================================================================
 
  int32_t setBreakpoint(const std::string &file, uint32_t line, const std::string &condition = "");
 
  bool removeBreakpoint(int32_t breakpoint_id);
 
  [[nodiscard]] std::vector<BreakpointInfo> getBreakpoints() const;
 
  [[nodiscard]] std::optional<BreakpointInfo> getBreakpoint(int32_t breakpoint_id) const;
 
  bool waitForBreakpoint(uint32_t timeout_ms = 0);
 
  // =========================================================================
  // Expression Evaluation
  // =========================================================================
 
  [[nodiscard]] std::optional<VariableInfo> evaluateExpression(const std::string &expression,
                                                               uint32_t frame_index = 0) const;
 
private:
  // LLDB objects (mutable because LLDB's SB API methods aren't const-correct)
  mutable lldb::SBDebugger debugger_;
  mutable lldb::SBTarget target_;
  mutable lldb::SBProcess process_;
  mutable lldb::SBListener listener_;
 
  // State
  bool initialized_ = false;
  mutable std::string last_error_;
 
  // Helper methods
  void setError(const std::string &msg) const;
  void clearError() const;
 
  // Drain pending LLDB events to synchronize process state
  void syncProcessState() const;
 
  // Wait for process to reach a specific state (with timeout in seconds)
  bool waitForState(lldb::StateType target_state, uint32_t timeout_sec = 5) const;
 
  [[nodiscard]] lldb::SBThread getSelectedThreadInternal() const;
  [[nodiscard]] lldb::SBFrame getFrameInternal(uint32_t index) const;
 
  // Note: LLDB SB API methods are not const in LLVM 21+, so we use non-const references
  [[nodiscard]] static ThreadInfo threadToInfo(lldb::SBThread &thread, bool is_selected);
  [[nodiscard]] static FrameInfo frameToInfo(lldb::SBFrame &frame);
  [[nodiscard]] VariableInfo valueToInfo(lldb::SBValue value, uint32_t expand_depth) const;
  [[nodiscard]] static BreakpointInfo breakpointToInfo(lldb::SBBreakpoint bp);
};
 
} // namespace ascii_query