ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
lldb_controller.h
Go to the documentation of this file.
1
13
14#pragma once
15
16#include <lldb/API/LLDB.h>
17
18#include <cstdint>
19#include <functional>
20#include <memory>
21#include <optional>
22#include <string>
23#include <vector>
24
25// Windows doesn't define pid_t, use LLDB's definition
26#ifdef _WIN32
27using pid_t = lldb::pid_t;
28#endif
29
30namespace ascii_query {
31
51
55struct ThreadInfo {
58 std::string name;
59 std::string stop_reason;
60 std::string function;
61 std::string file;
64};
65
77
82 std::string name;
83 std::string type;
84 std::string value;
85 std::string summary;
87 size_t size;
88 bool is_valid;
91
92 std::vector<VariableInfo> children;
93};
94
99 int32_t id;
100 std::string file;
102 std::string condition;
104 bool enabled;
105 bool resolved;
106};
107
115public:
118
119 // Non-copyable, non-movable (owns LLDB resources)
124
125 // =========================================================================
126 // Initialization
127 // =========================================================================
128
133 bool initialize();
134
138 void shutdown();
139
140 // =========================================================================
141 // Process Attachment
142 // =========================================================================
143
151 bool attach(pid_t pid);
152
159 bool attachByName(const std::string &process_name, bool wait_for = false);
160
166 void detach();
167
172 [[nodiscard]] bool isAttached() const;
173
178 [[nodiscard]] pid_t targetPid() const;
179
184 [[nodiscard]] std::string targetName() const;
185
186 // =========================================================================
187 // Process Control
188 // =========================================================================
189
194 bool stop();
195
200 bool resume();
201
206 bool stepInto();
207
212 bool stepOver();
213
218 bool stepOut();
219
224 [[nodiscard]] ProcessState state() const;
225
230 [[nodiscard]] const std::string &lastError() const;
231
232 // =========================================================================
233 // Thread Information
234 // =========================================================================
235
240 [[nodiscard]] std::vector<ThreadInfo> getThreads() const;
241
246 [[nodiscard]] std::optional<ThreadInfo> getSelectedThread() const;
247
253 bool selectThread(uint64_t thread_id);
254
255 // =========================================================================
256 // Stack Frames
257 // =========================================================================
258
264 [[nodiscard]] std::vector<FrameInfo> getFrames(uint32_t max_frames = 0) const;
265
271 [[nodiscard]] std::optional<FrameInfo> getFrame(uint32_t frame_index) const;
272
273 // =========================================================================
274 // Variable Reading
275 // =========================================================================
276
284 [[nodiscard]] std::optional<VariableInfo> readVariable(const std::string &name, uint32_t frame_index = 0, uint32_t expand_depth = 0) const;
285
294 [[nodiscard]] std::vector<VariableInfo> listVariables(uint32_t frame_index = 0, bool include_args = true, bool include_locals = true, bool include_statics = false) const;
295
296 // =========================================================================
297 // Breakpoints
298 // =========================================================================
299
307 int32_t setBreakpoint(const std::string &file, uint32_t line, const std::string &condition = "");
308
314 bool removeBreakpoint(int32_t breakpoint_id);
315
320 [[nodiscard]] std::vector<BreakpointInfo> getBreakpoints() const;
321
327 [[nodiscard]] std::optional<BreakpointInfo> getBreakpoint(int32_t breakpoint_id) const;
328
334 bool waitForBreakpoint(uint32_t timeout_ms = 0);
335
336 // =========================================================================
337 // Expression Evaluation
338 // =========================================================================
339
346 [[nodiscard]] std::optional<VariableInfo> evaluateExpression(const std::string &expression, uint32_t frame_index = 0) const;
347
348private:
349 // LLDB objects (mutable because LLDB's SB API methods aren't const-correct)
350 mutable lldb::SBDebugger debugger_;
351 mutable lldb::SBTarget target_;
352 mutable lldb::SBProcess process_;
353 mutable lldb::SBListener listener_;
354
355 // State
356 bool initialized_ = false;
357 mutable std::string last_error_;
358
359 // Helper methods
360 void setError(const std::string &msg) const;
361 void clearError() const;
362
363 // Drain pending LLDB events to synchronize process state
364 void syncProcessState() const;
365
366 // Wait for process to reach a specific state (with timeout in seconds)
367 bool waitForState(lldb::StateType target_state, uint32_t timeout_sec = 5) const;
368
369 [[nodiscard]] lldb::SBThread getSelectedThreadInternal() const;
370 [[nodiscard]] lldb::SBFrame getFrameInternal(uint32_t index) const;
371
372 // Note: LLDB SB API methods are not const in LLVM 21+, so we use non-const references
373 [[nodiscard]] static ThreadInfo threadToInfo(lldb::SBThread &thread, bool is_selected);
374 [[nodiscard]] static FrameInfo frameToInfo(lldb::SBFrame &frame);
375 [[nodiscard]] VariableInfo valueToInfo(lldb::SBValue value, uint32_t expand_depth) const;
376 [[nodiscard]] static BreakpointInfo breakpointToInfo(lldb::SBBreakpoint bp);
377};
378
379} // namespace ascii_query
int32_t setBreakpoint(const std::string &file, uint32_t line, const std::string &condition="")
Set a breakpoint at file:line.
std::optional< VariableInfo > evaluateExpression(const std::string &expression, uint32_t frame_index=0) const
Evaluate an expression in the current context.
bool attachByName(const std::string &process_name, bool wait_for=false)
Attach to a process by name.
bool removeBreakpoint(int32_t breakpoint_id)
Remove a breakpoint.
bool stepInto()
Single step the current thread (step into).
pid_t targetPid() const
Get the PID of the attached process.
LLDBController & operator=(LLDBController &&)=delete
std::string targetName() const
Get the name of the attached process.
bool selectThread(uint64_t thread_id)
Select a thread by ID.
std::optional< VariableInfo > readVariable(const std::string &name, uint32_t frame_index=0, uint32_t expand_depth=0) const
Read a variable from the current frame.
const std::string & lastError() const
Get the last error message.
std::vector< VariableInfo > listVariables(uint32_t frame_index=0, bool include_args=true, bool include_locals=true, bool include_statics=false) const
List all variables in scope at a frame.
bool initialize()
Initialize LLDB. Must be called before any other methods.
void shutdown()
Shutdown LLDB and release resources.
LLDBController(LLDBController &&)=delete
bool stop()
Stop the target process.
bool isAttached() const
Check if attached to a process.
LLDBController & operator=(const LLDBController &)=delete
LLDBController(const LLDBController &)=delete
std::vector< ThreadInfo > getThreads() const
Get list of all threads.
std::optional< FrameInfo > getFrame(uint32_t frame_index) const
Get a specific frame by index.
std::vector< BreakpointInfo > getBreakpoints() const
Get all breakpoints.
bool resume()
Resume the target process.
std::vector< FrameInfo > getFrames(uint32_t max_frames=0) const
Get stack frames for the selected thread.
bool stepOver()
Step over the current line.
std::optional< BreakpointInfo > getBreakpoint(int32_t breakpoint_id) const
Get information about a specific breakpoint.
bool stepOut()
Step out of the current function.
void detach()
Detach from the current process.
bool attach(pid_t pid)
Attach to a process by PID.
ProcessState state() const
Get the current process state.
std::optional< ThreadInfo > getSelectedThread() const
Get the currently selected thread.
bool waitForBreakpoint(uint32_t timeout_ms=0)
Wait for any breakpoint to be hit.
unsigned int uint32_t
unsigned long long uint64_t
ProcessState
This is the handoff point for ThreadInfo. Callers fill its members before passing it on; consumers re...
@ Exited
Process has exited.
@ Crashed
Process crashed.
@ Detached
Detached from process.
@ Invalid
No valid process attached.
@ Running
Process is running normally.
@ Stopped
Process is stopped (breakpoint, signal, etc.).
static bool size_t index
Definition queries.h:8
Breakpoint information.
int32_t id
LLDB breakpoint ID.
std::string condition
Condition expression (may be empty).
bool enabled
Is breakpoint enabled?
uint32_t line
Line number.
bool resolved
Is breakpoint resolved (has valid location)?
uint32_t hit_count
Number of times hit.
std::string file
Source file.
Stack frame information.
uint32_t line
Line number.
std::string function
Function name.
uint64_t pc
Program counter.
uint64_t fp
Frame pointer.
uint32_t index
Frame index (0 = innermost).
std::string file
Source file.
Thread information.
std::string name
Thread name (may be empty).
uint32_t line
Current line number.
uint64_t id
Thread ID.
bool is_selected
Is this the selected thread?
std::string stop_reason
Why thread is stopped (if stopped).
std::string function
Current function name.
uint32_t index
Index in thread list.
std::string file
Current source file.
Variable information (from LLDB SBValue).
std::vector< VariableInfo > children
Struct members / array elements.
std::string value
Value as string.
bool is_aggregate
Whether this is struct/class/array.
size_t size
Size in bytes.
std::string type
Type name.
std::string name
Variable name.
bool is_pointer
Whether this is a pointer type.
std::string summary
LLDB summary (for complex types).
bool is_valid
Whether value could be read.
uint64_t address
Memory address.