Debian Codegraph @

cross-project-tests/debuginfo-tests/dexter/dex/debugger/DAP.py

raw
1 # DExTer : Debugging Experience Tester
2 # ~~~~~~ ~ ~~ ~ ~~
3 #
4 # Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
5 # See https://llvm.org/LICENSE.txt for license information.
6 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 """Interface for communicating with a debugger via the DAP.
8 """
9
10 import abc
11 from collections import defaultdict
12 import copy
13 import json
14 import os
15 import shlex
16 import subprocess
17 import sys
18 import threading
19 import time
20 from enum import Enum
21
22 from dex.debugger.DebuggerBase import DebuggerBase, watch_is_active
23 from dex.dextIR import FrameIR, LocIR, StepIR, StopReason, ValueIR
24 from dex.dextIR import StackFrame, SourceLocation, ProgramState
25 from dex.utils.Exceptions import DebuggerException, LoadDebuggerException
26 from dex.utils.ReturnCode import ReturnCode
27 from dex.utils.Logging import Logger
28 from dex.utils.Timeout import Timeout
29
30
31 # Helper enum used for colorizing DAP Message Log output.
32 class Color(Enum):
33 CYAN = 36
34 GREEN = 32
35 YELLOW = 33
36 RED = 31
37 MAGENTA = 35
38
39 def apply(self, text: str) -> str:
40 return f"\033[{self.value}m{text}\033[0m"
41
42
43 class DAPMessageLogger:
44 def __init__(self, context):
45 self.dexter_logger = context.logger
46 self.log_file: str = context.options.dap_message_log
47 self.colorized: bool = context.options.colorize_dap_log
48 self.indent = 2 if context.options.format_dap_log == "pretty" else None
49 self.prefix_send: str = "->"
50 self.prefix_recv: str = "<-"
51 self.out_handle = None
52 self.open = False
53 self.lock = threading.Lock()
54
55 def _custom_enter(self):
56 self.open = True
57 if self.log_file is None:
58 return
59 if self.log_file == "-":
60 self.out_handle = sys.stdout
61 return
62 if self.log_file == "-e":
63 self.out_handle = sys.stderr
64 return
65 self.out_handle = open(self.log_file, "w+", encoding="utf-8")
66
67 def _custom_exit(self):
68 if (
69 self.out_handle is not None
70 and self.log_file != "-"
71 and self.log_file != "-e"
72 ):
73 self.out_handle.close()
74 self.open = False
75
76 def _colorize_dap_message(self, message: dict) -> dict:
77 if not self.colorized:
78 return message
79 colorized_message = copy.deepcopy(message)
80 if colorized_message["type"] == "event":
81 colorized_message["type"] = Color.YELLOW.apply("event")
82 colorized_message["event"] = Color.YELLOW.apply(colorized_message["event"])
83 elif colorized_message["type"] == "response":
84 colorized_message["type"] = Color.GREEN.apply("response")
85 colorized_message["command"] = Color.YELLOW.apply(
86 colorized_message["command"]
87 )
88 elif colorized_message["type"] == "request":
89 colorized_message["type"] = Color.CYAN.apply("request")
90 colorized_message["command"] = Color.YELLOW.apply(
91 colorized_message["command"]
92 )
93 return colorized_message
94
95 def write_message(self, message: dict, incoming: bool):
96 prefix = self.prefix_recv if incoming else self.prefix_send
97 # ANSI escape codes get butchered by json.dumps(), so we fix them up here.
98 message_str = json.dumps(
99 self._colorize_dap_message(message), indent=self.indent
100 ).replace("\\u001b", "\033")
101 if self.out_handle is not None and self.open:
102 with self.lock:
103 self.out_handle.write(f"{prefix} {message_str}\n")
104 elif not self.open:
105 self.dexter_logger.warning(
106 f'Attempted to write message after program closed: "{prefix} {message_str}"'
107 )
108
109
110 # Debuggers communicate optional feature support.
111 class DAPDebuggerCapabilities:
112 def __init__(self):
113 self.supportsConfigurationDoneRequest: bool = False
114 self.supportsFunctionBreakpoints: bool = False
115 self.supportsConditionalBreakpoints: bool = False
116 self.supportsHitConditionalBreakpoints: bool = False
117 self.supportsEvaluateForHovers: bool = False
118 self.supportsSetVariable: bool = False
119 self.supportsStepInTargetsRequest: bool = False
120 self.supportsModulesRequest: bool = False
121 self.supportsValueFormattingOptions: bool = False
122 self.supportsLogPoints: bool = False
123 self.supportsSetExpression: bool = False
124 self.supportsDataBreakpoints: bool = False
125 self.supportsReadMemoryRequest: bool = False
126 self.supportsWriteMemoryRequest: bool = False
127 self.supportsDisassembleRequest: bool = False
128 self.supportsCancelRequest: bool = False
129 self.supportsSteppingGranularity: bool = False
130 self.supportsInstructionBreakpoints: bool = False
131
132 def update(self, logger: Logger, feature_dict: dict):
133 for k, v in feature_dict.items():
134 if hasattr(self, k):
135 setattr(self, k, v)
136 else:
137 logger.warning(f"DAP: Unknown support flag: {k}")
138
139
140 # As DAP does not give us a trivially query-able process, we are responsible for maintaining our own state information,
141 # including what breakpoints are currently set, and whether the debugger is running or stopped.
142 # This class holds all state that is set based on events sent by the debug adapter; most responses are forwarded through
143 # to the main DAP class, though in a few cases where it is convenient for bookkeeping the DAPDebuggerState may read some
144 # information from the responses before forwarding them onwards.
145 class DAPDebuggerState:
146 def __init__(self):
147 ## Overall debugger state information.
148 #
149 # Whether we have received the initialize update yet.
150 self.initialized: bool = False
151 # Whether the debugger has successfully launched yet.
152 self.launched: bool = False
153 # The thread that we are debugging.
154 # TODO: This is primitively handled right now, assuming that we only ever have one thread; if we want
155 # support for debugging any multi-threaded program then we will need to track some more complex state.
156 self.thread = None
157 # True if the debuggee is currently executing.
158 self.is_running: bool = False
159 # True if the debuggee has finished executing.
160 self.is_finished: bool = False
161
162 ## Information for the program at a particular stopped point, which will be invalidated when execution resumes.
163 #
164 # Either None if the debuggee is currently running, or a string specifying the reason why the
165 # debuggee is currently stopped otherwise.
166 self.stopped_reason = None
167 # If we were stopped for the reason 'breakpoint', this will contain a list of the DAP breakpoint IDs
168 # responsible for stopping us.
169 self.stopped_bps = []
170 # For a currently stopped process, stores the mapping of frame indices (top of stack=0) to frameIds returned
171 # from the debug adapter.
172 self.frame_map = []
173
174 # We use responses[idx] to refer to the response for the request sent with seq=idx, where the value
175 # is either the response payload, or None if the response hasn't arrived yet.
176 # Since requests are indexed from 1, we insert a 'None' at the front to ensure that the first real
177 # entry is indexed correctly.
178 self.responses = [None]
179 # Map of DAP breakpoint IDs to resolved instruction addresses.
180 self.bp_addr_map = {}
181
182 # DAP features supported by the debugger.
183 self.capabilities = DAPDebuggerCapabilities()
184
185 def set_response(self, req_id: int, response: dict):
186 if len(self.responses) > req_id:
187 self.responses[req_id] = response
188 return
189 while len(self.responses) < req_id:
190 self.responses.append(None)
191 self.responses.append(response)
192
193 # As the receiver thread does not know when a request has been sent, and only the receiver thread should write to the DebuggerState object,
194 # the responses list may not have been populated with a None for a pending request at the time that the main thread expects it. Therefore,
195 # we use this getter to account for requests that the receiver thread is unaware of.
196 def get_response(self, req_id: int):
197 if len(self.responses) <= req_id:
198 return None
199 return self.responses[req_id]
200
201
202 # DAP Communication model:
203 # - Communication is message-based, not stateful - we cannot simply query information from the debugger as we can with
204 # other debugger implementations, we need to maintain local state.
205 # - All messages are utf-encoded JSON, which we convert to/from python dicts via methods above; some amount of
206 # bookkeeping is performed automatically in the DAP class.
207 # - Commands and queries are sent via 'request' messages, for which a corresponding 'response' will always be sent back
208 # by the adapter indicating success/failure, containing data related to the request.
209 # - The adapter will also send 'event' messages, indicating state changes in the debugger - for example, when the
210 # debugger has stopped at a breakpoint.
211 # In order to handle this, we run a separate thread that will continuously insert any messages received
212 # from the adapter into a queue, which the main thread will read; generally, our response to any read message
213 # is to update our state, which Dexter's DebuggerController will then read.
214 class DAP(DebuggerBase, metaclass=abc.ABCMeta):
215 def __init__(self, context, *args):
216 self._debugger_state = DAPDebuggerState()
217 self._proc = None
218 self._receiver_thread = None
219 self._err_thread = None
220 self.seq = 0
221 self.target_proc_id = -1
222 self.max_bp_id = 0
223 # Mapping of active breakpoints per-file - intentionally excludes breakpoints that we have deleted.
224 # { file -> [dex_breakpoint_id]}
225 self.file_to_bp = defaultdict(list)
226 # { dex_breakpoint_id -> (file, line, condition) }
227 self.bp_info = {}
228 # { dex_breakpoint_id -> function_name }
229 self.function_bp_info = {}
230 # { dex_breakpoint_id -> instruction_reference }
231 self.instruction_bp_info = {}
232 # We don't rely on IDs returned directly from the debug adapter. Instead, we use dexter breakpoint IDs, and
233 # maintain a two-way-mapping of dex_bp_id<->dap_bp_id. This also allows us to defer the setting of breakpoints
234 # in the debug adapter itself until necessary.
235 # NB: The debug adapter may merge dexter-side breakpoints into a single debugger-side breakpoint; therefore, the
236 # DAP->Dex mapping is one-to-many.
237 self.dex_id_to_dap_id = {}
238 self.dap_id_to_dex_ids = {}
239 self.pending_breakpoints: bool = False
240 self.pending_function_breakpoints: bool = False
241 self.pending_instruction_breakpoints: bool = False
242 # List of breakpoints, indexed by BP ID
243 # Each entry has the source file (for use in referencing desired_bps), and the DA-assigned
244 # ID for that breakpoint if it has one (if it has been removed or not yet created then it will be None).
245 # self.bp_source_list: list[(str, int)]
246 self.message_logger = None
247 super(DAP, self).__init__(context, *args)
248
249 @property
250 @abc.abstractmethod
251 def _debug_adapter_name(self) -> str:
252 pass
253
254 @property
255 @abc.abstractmethod
256 def _debug_adapter_executable(self) -> str:
257 pass
258
259 @property
260 def _debug_adapter_launch_args(self) -> list:
261 return []
262
263 @staticmethod
264 def make_request(command: str, arguments=None) -> dict:
265 request = {"type": "request", "command": command}
266 if arguments is not None:
267 request["arguments"] = arguments
268 return request
269
270 @staticmethod
271 def make_initialize_request(adapterID: str) -> dict:
272 return DAP.make_request(
273 "initialize",
274 {
275 "clientID": "dexter",
276 "adapterID": adapterID,
277 "pathFormat": "path",
278 "linesStartAt1": True,
279 "columnsStartAt1": True,
280 "supportsVariableType": True,
281 "supportsVariablePaging": True,
282 "supportsRunInTerminalRequest": False,
283 },
284 )
285
286 class BreakpointRequest:
287 def __init__(self, line: int, condition=None):
288 self.line = line
289 self.condition = condition
290
291 def toDict(self) -> dict:
292 result = {"line": self.line}
293 if self.condition is not None:
294 result["condition"] = self.condition
295 return result
296
297 @staticmethod
298 def make_set_breakpoint_request(source: str, bps) -> dict:
299 return DAP.make_request(
300 "setBreakpoints",
301 {"source": {"path": source}, "breakpoints": [bp.toDict() for bp in bps]},
302 )
303
304 @staticmethod
305 def make_set_function_breakpoint_request(function_names: list) -> dict:
306 # Function breakpoints may specify conditions and hit counts, though we
307 # don't use those here (though perhaps we should use native hit count,
308 # rather than emulating it ConditionalController, now that we have a
309 # shared interface (DAP)).
310 return DAP.make_request(
311 "setFunctionBreakpoints",
312 {"breakpoints": [{"name": f} for f in function_names]},
313 )
314
315 @staticmethod
316 def make_set_instruction_breakpoint_request(addrs: list) -> dict:
317 # Instruction breakpoints have additional fields we're ignoring for the
318 # moment.
319 return DAP.make_request(
320 "setInstructionBreakpoints",
321 {"breakpoints": [{"instructionReference": a} for a in addrs]},
322 )
323
324 ############################################################################
325 ## DAP communication & state-handling functions
326
327 # Sends a request to the adapter, returning the seq value of the request.
328 def send_message(self, payload: dict) -> int:
329 self.seq = self.seq + 1
330 payload["seq"] = self.seq
331 self.message_logger.write_message(payload, False)
332 body = json.dumps(payload)
333 message = f"Content-Length: {len(body)}\r\n\r\n{body}".encode("utf-8")
334 self._proc.stdin.write(message)
335 self._proc.stdin.flush()
336 return self.seq
337
338 @staticmethod
339 def _handle_message(
340 message: dict, debugger_state: DAPDebuggerState, logger: Logger
341 ):
342 # We only support events and responses, we do not implement any reverse-requests.
343 # TODO: If we find cases where 'seq' becomes important, we need to read it here and process
344 # pending messages in order.
345 if message["type"] == "event":
346 event_type = message["event"]
347 event_details = message.get("body")
348 if event_type == "initialized":
349 debugger_state.initialized = True
350 elif event_type == "process":
351 debugger_state.launched = True
352 debugger_state.is_running = True
353 # The debugger has stopped for some reason.
354 elif event_type == "stopped":
355 stop_reason = event_details["reason"]
356 debugger_state.is_running = False
357 debugger_state.stopped_reason = stop_reason
358 debugger_state.stopped_bps = event_details.get("hitBreakpointIds", [])
359 debugger_state.thread = event_details["threadId"]
360 elif event_type == "breakpoint":
361 # We handle most BP information in the main DAP thread by reading responses to breakpoint requests;
362 # some information is only passed via event, however, which we store here.
363 breakpoint_details = event_details["breakpoint"]
364 if "instructionReference" in breakpoint_details:
365 debugger_state.bp_addr_map[
366 breakpoint_details["id"]
367 ] = breakpoint_details["instructionReference"]
368 elif event_type == "exited" or event_type == "terminated":
369 debugger_state.stopped_reason = event_type
370 debugger_state.is_running = False
371 debugger_state.is_finished = True
372 # We may receive this event before or after the response to the corresponding "continue" request.
373 elif event_type == "continued":
374 debugger_state.is_running = True
375 # Reset all state that is invalidated upon program continue.
376 debugger_state.stopped_reason = None
377 debugger_state.stopped_bps = []
378 debugger_state.frame_map = []
379 elif event_type == "thread":
380 if (
381 event_details["reason"] == "started"
382 and debugger_state.thread is None
383 ):
384 debugger_state.thread = event_details["threadId"]
385 elif event_type == "capabilities":
386 # Unchanged capabilites may not be included.
387 debugger_state.capabilities.update(logger, event_details)
388 # There are many events we do not care about, just skip processing them.
389 else:
390 pass
391 elif message["type"] == "response":
392 # TODO: We also receive a "continued" event, but it seems reasonable to set state based on either the
393 # response or the event, since the DAP does not specify an order in which they are sent. May need revisiting
394 # if there turns out to be some odd ordering issues, e.g. if we can receive messages in the order
395 # ["response: continued", "event: stopped", "event: continued"].
396 if (
397 message["command"] in ["continue", "stepIn", "next", "stepOut"]
398 and message["success"] == True
399 ):
400 debugger_state.is_running = True
401 # Reset all state that is invalidated upon program continue.
402 debugger_state.stopped_reason = None
403 debugger_state.stopped_bps = []
404 debugger_state.frame_map = []
405 # It is useful to cache a mapping of frames; since this is invalidated when we continue, and only this
406 # message-handling thread should write to debugger_state, we do so while handling the response for
407 # convenience.
408 if message["command"] == "stackTrace" and message["success"] == True:
409 debugger_state.frame_map = [
410 stackframe["id"] for stackframe in message["body"]["stackFrames"]
411 ]
412 # The debugger communicates which optional DAP features are
413 # supported in its initalize response.
414 if message["command"] == "initialize" and message["success"] == True:
415 body = message.get("body")
416 if body:
417 debugger_state.capabilities.update(logger, body)
418 # Now we've done whatever we need to do with the response, tell the
419 # receiver thread we've got it.
420 request_seq = message["request_seq"]
421 debugger_state.set_response(request_seq, message)
422
423 @staticmethod
424 def _colorize_dap_message(message: dict) -> dict:
425 colorized_message = copy.deepcopy(message)
426 if colorized_message["type"] == "event":
427 colorized_message["type"] = "<y>event</>"
428 colorized_message["event"] = f"<y>{colorized_message['event']}</>"
429 elif colorized_message["type"] == "response":
430 colorized_message["type"] = "<g>response</>"
431 colorized_message["command"] = f"<y>{colorized_message['command']}</>"
432 elif colorized_message["type"] == "request":
433 colorized_message["type"] = "<b>request</>"
434 colorized_message["command"] = f"<y>{colorized_message['command']}</>"
435 return colorized_message
436
437 @staticmethod
438 def _read_dap_output(
439 proc: subprocess.Popen,
440 debugger_state: DAPDebuggerState,
441 message_logger: DAPMessageLogger,
442 logger: Logger,
443 ):
444 buffer: bytes = b""
445 while True:
446 chunk: bytes = proc.stdout.read(1)
447 if not chunk:
448 break
449 buffer += chunk
450 if b"\r\n\r\n" in buffer:
451 header, rest = buffer.split(b"\r\n\r\n", 1)
452 content_length = int(header.decode().split(":")[1].strip())
453 while len(rest) < content_length:
454 rest += proc.stdout.read(content_length - len(rest))
455 message = json.loads(rest[:content_length])
456 message_logger.write_message(message, True)
457 DAP._handle_message(message, debugger_state, logger)
458 buffer = rest[content_length:]
459
460 @staticmethod
461 def _read_dap_err(proc: subprocess.Popen, logger: Logger):
462 while True:
463 err: bytes = proc.stderr.readline()
464 if len(err) > 0:
465 logger.error(f"DAP server: {err.decode().strip()}")
466
467 def _custom_init(self):
468 self.context.logger.note(
469 f"Opening DAP server: {shlex.join([self._debug_adapter_executable] + self._debug_adapter_launch_args)}"
470 )
471 self.message_logger = DAPMessageLogger(self.context)
472 self.message_logger._custom_enter()
473 self._proc = subprocess.Popen(
474 [self._debug_adapter_executable] + self._debug_adapter_launch_args,
475 stdin=subprocess.PIPE,
476 stdout=subprocess.PIPE,
477 stderr=subprocess.PIPE,
478 bufsize=0,
479 )
480 self._receiver_thread = threading.Thread(
481 target=DAP._read_dap_output,
482 args=(
483 self._proc,
484 self._debugger_state,
485 self.message_logger,
486 self.context.logger,
487 ),
488 daemon=True,
489 )
490 self._err_thread = threading.Thread(
491 target=DAP._read_dap_err,
492 args=(self._proc, self.context.logger),
493 daemon=True,
494 )
495 self._receiver_thread.start()
496 self._err_thread.start()
497 init_req = self.send_message(
498 self.make_initialize_request(self._debug_adapter_name)
499 )
500 assert self._proc.poll() is None, "Process has closed unexpectedly early?"
501 self._await_response(init_req)
502
503 def _custom_exit(self):
504 if self._proc is not None:
505 dc_req = self.send_message(self.make_request("disconnect"))
506 dc_req_timeout = 3
507 try:
508 result = self._await_response(dc_req, dc_req_timeout)
509 if not result["success"]:
510 self.context.logger.warning(
511 "The disconnect request sent to the DAP server failed; forcibly shutting down DAP server."
512 )
513 else:
514 self.context.logger.note(
515 "Successfully disconnected from DAP server."
516 )
517 except:
518 # We're going to kill the process regardless, we just want to give the target a chance to shut down
519 # gracefully first.
520 self.context.logger.warning(
521 f"The disconnect request sent to the DAP server timed out after {dc_req_timeout}s; forcibly shutting down DAP server."
522 )
523 pass
524 self._proc.kill()
525 self._proc = None
526 self.message_logger._custom_exit()
527
528 # Waits for a response to the request with the given seq, optionally raising an error
529 # if the response takes too long (blocks forever by default/if timeout=0).
530 def _await_response(self, seq: int, timeout: float = 0.0) -> dict:
531 timeout_check = Timeout(timeout)
532 while self._debugger_state.get_response(seq) is None:
533 if timeout_check.timed_out():
534 if self._proc.poll() is not None:
535 self.context.logger.error(
536 f"Debug adapter exited while Dexter is awaiting response? Result: {self._proc.poll()}"
537 )
538 raise TimeoutError(
539 f"Timed out while waiting for response to DAP request {seq}"
540 )
541 time.sleep(0.001)
542 return self._debugger_state.get_response(seq)
543
544 ## End of DAP communication methods
545 ############################################################################
546
547 def _translate_stop_reason(self, reason):
548 if reason is None:
549 return None
550 if "breakpoint" in reason:
551 return StopReason.BREAKPOINT
552 if reason == "step":
553 return StopReason.STEP
554 if reason == "exited" or reason == "terminated":
555 return StopReason.PROGRAM_EXIT
556 if reason == "exception":
557 return StopReason.ERROR
558 return StopReason.OTHER
559
560 def _load_interface(self):
561 if not os.path.isfile(self._debug_adapter_executable):
562 raise LoadDebuggerException(
563 f'debug adapter "{self._debug_adapter_executable}" does not exist',
564 sys.exc_info(),
565 )
566 # We don't make use of _interface, so return nothing.
567
568 @property
569 @abc.abstractmethod
570 def version(self):
571 """The version of this DAP debugger."""
572
573 ############################################################################
574 ## Breakpoint Methods
575
576 def get_next_bp_id(self):
577 new_id = self.max_bp_id
578 self.max_bp_id += 1
579 return new_id
580
581 def get_current_bps(self, source):
582 if source in self.file_to_bp:
583 return self.file_to_bp[source]
584 return []
585
586 def _update_requested_bp_list(self, bp_list):
587 """Can be overridden for any specific implementations that need further processing before sending breakpoints to
588 the debug adapter, e.g. in LLDB we cannot store multiple breakpoints at a single location, and therefore must
589 combine conditions for breakpoints at the same location."""
590 return bp_list
591
592 # For a source file, returns the list of BreakpointRequests for the breakpoints in that file, which can be sent to
593 # the debug adapter.
594 def _get_desired_bps(self, file: str):
595 bp_list = [
596 DAP.BreakpointRequest(line, cond)
597 for (_, line, cond) in map(
598 lambda dex_bp_id: self.bp_info[dex_bp_id], self.get_current_bps(file)
599 )
600 ]
601 return self._update_requested_bp_list(bp_list)
602
603 def clear_breakpoints(self):
604 # We don't actually need to do anything here - even if breakpoints were preserved between runs, we will
605 # automatically clear old breakpoints on the first 'setBreakpoints' message.
606 pass
607
608 def _add_breakpoint(self, file, line):
609 return self._add_conditional_breakpoint(file, line, None)
610
611 def add_function_breakpoint(self, name: str):
612 if not self._debugger_state.capabilities.supportsFunctionBreakpoints:
613 raise DebuggerException("Debugger does not support function breakpoints")
614 new_id = self.get_next_bp_id()
615 self.function_bp_info[new_id] = name
616 self.pending_function_breakpoints = True
617 return new_id
618
619 def add_instruction_breakpoint(self, addr: str):
620 if not self._debugger_state.capabilities.supportsInstructionBreakpoints:
621 raise DebuggerException("Debugger does not support instruction breakpoints")
622 new_id = self.get_next_bp_id()
623 self.instruction_bp_info[new_id] = addr
624 self.pending_instruction_breakpoints = True
625 return new_id
626
627 def _add_conditional_breakpoint(self, file, line, condition):
628 new_id = self.get_next_bp_id()
629 self.file_to_bp[file].append(new_id)
630 self.bp_info[new_id] = (file, line, condition)
631 self.pending_breakpoints = True
632 return new_id
633
634 def _update_breakpoint_ids_after_request(self, dex_bp_ids: list, response: dict):
635 dap_bp_ids = [bp["id"] for bp in response["body"]["breakpoints"]]
636 if len(dex_bp_ids) != len(dap_bp_ids):
637 self.context.logger.error(
638 f"Sent request to set {len(dex_bp_ids)} breakpoints, but received {len(dap_bp_ids)} in response."
639 )
640 visited_dap_ids = set()
641 for i, dex_bp_id in enumerate(dex_bp_ids):
642 dap_bp_id = dap_bp_ids[i]
643 self.dex_id_to_dap_id[dex_bp_id] = dap_bp_id
644 # We take the mappings in the response as the canonical mapping, meaning that if the debug server has
645 # simply *changed* the DAP ID for a breakpoint we overwrite the existing mapping rather than adding to
646 # it, but if we receive the same DAP ID for multiple Dex IDs *then* we store a one-to-many mapping.
647 if dap_bp_id in visited_dap_ids:
648 self.dap_id_to_dex_ids[dap_bp_id].append(dex_bp_id)
649 else:
650 self.dap_id_to_dex_ids[dap_bp_id] = [dex_bp_id]
651 visited_dap_ids.add(dap_bp_id)
652
653 def _flush_breakpoints(self):
654 # Normal and conditional breakpoints.
655 if self.pending_breakpoints:
656 self.pending_breakpoints = False
657 for file in self.file_to_bp.keys():
658 desired_bps = self._get_desired_bps(file)
659 request_id = self.send_message(
660 self.make_set_breakpoint_request(file, desired_bps)
661 )
662 result = self._await_response(request_id, 10)
663 if not result["success"]:
664 raise DebuggerException(f"could not set breakpoints for '{file}'")
665 # The debug adapter may have chosen to merge our breakpoints. From here we need to identify such cases and
666 # handle them so that our internal bookkeeping is correct.
667 dex_bp_ids = self.get_current_bps(file)
668 self._update_breakpoint_ids_after_request(dex_bp_ids, result)
669
670 # Function breakpoints.
671 if self.pending_function_breakpoints:
672 self.pending_function_breakpoints = False
673 desired_bps = list(self.function_bp_info.values())
674 request_id = self.send_message(
675 self.make_set_function_breakpoint_request(desired_bps)
676 )
677 result = self._await_response(request_id, 10)
678 if not result["success"]:
679 raise DebuggerException(
680 f"could not set function breakpoints: '{desired_bps}'"
681 )
682 # We expect the breakpoint order to match in request and response.
683 dex_bp_ids = list(self.function_bp_info.keys())
684 self._update_breakpoint_ids_after_request(dex_bp_ids, result)
685
686 # Address / instruction breakpoints.
687 if self.pending_instruction_breakpoints:
688 self.pending_instruction_breakpoints = False
689 desired_bps = list(self.instruction_bp_info.values())
690 request_id = self.send_message(
691 self.make_set_instruction_breakpoint_request(desired_bps)
692 )
693 result = self._await_response(request_id, 10)
694 if not result["success"]:
695 raise DebuggerException(
696 f"could not set instruction breakpoints: '{desired_bps}'"
697 )
698 # We expect the breakpoint order to match in request and response.
699 dex_bp_ids = list(self.instruction_bp_info.keys())
700 self._update_breakpoint_ids_after_request(dex_bp_ids, result)
701
702 def _confirm_triggered_breakpoint_ids(self, dex_bp_ids):
703 """Can be overridden for any specific implementations that need further processing from the debug server's
704 reported 'hitBreakpointIds', e.g. in LLDB where we the ID for every breakpoint at the current PC, even if some
705 are conditional and their condition is not met."""
706 return dex_bp_ids
707
708 def get_triggered_breakpoint_ids(self):
709 # Breakpoints can only have been triggered if we've hit one.
710 stop_reason = self._translate_stop_reason(self._debugger_state.stopped_reason)
711 if stop_reason != StopReason.BREAKPOINT:
712 return set()
713 breakpoint_ids = set(
714 [
715 dex_id
716 for dap_id in self._debugger_state.stopped_bps
717 if dap_id in self.dap_id_to_dex_ids
718 for dex_id in self.dap_id_to_dex_ids[dap_id]
719 ]
720 )
721 return self._confirm_triggered_breakpoint_ids(breakpoint_ids)
722
723 def delete_breakpoints(self, ids):
724 per_file_deletions = defaultdict(list)
725 for dex_bp_id in ids:
726 if dex_bp_id in self.bp_info:
727 source, _, _ = self.bp_info[dex_bp_id]
728 per_file_deletions[source].append(dex_bp_id)
729 elif dex_bp_id in self.function_bp_info:
730 del self.function_bp_info[dex_bp_id]
731 self.pending_function_breakpoints = True
732 elif dex_bp_id in self.instruction_bp_info:
733 del self.instruction_bp_info[dex_bp_id]
734 self.pending_instruction_breakpoints = True
735
736 for file, deleted_ids in per_file_deletions.items():
737 old_len = len(self.file_to_bp[file])
738 self.file_to_bp[file] = [
739 bp_id for bp_id in self.file_to_bp[file] if bp_id not in deleted_ids
740 ]
741 if len(self.file_to_bp[file]) != old_len:
742 self.pending_breakpoints = True
743
744 ## End of breakpoint methods
745 ############################################################################
746
747 @classmethod
748 @abc.abstractmethod
749 def _get_launch_params(self, cmdline):
750 """ "Set the debugger-specific params used in a launch request."""
751
752 def launch(self, cmdline):
753 # FIXME: Should this be a warning or exception, rather than assert?
754 assert (
755 len(self.file_to_bp)
756 + len(self.function_bp_info)
757 + len(self.instruction_bp_info)
758 > 0
759 ), "Expected at least one breakpoint before launching"
760
761 if self.context.options.target_run_args:
762 cmdline += shlex.split(self.context.options.target_run_args)
763
764 launch_request = self._get_launch_params(cmdline)
765
766 # Per DAP protocol, we follow the sequence:
767 # 1. Send launch request
768 # 2. Set breakpoints
769 # 3. Send configurationDone to start the process
770 # 4. Wait for launch and configurationDone responses, and a "process" event, to confirm successful launch
771 # NB: Technically, we should also wait for the "initialized" event before sending the launch request, but in
772 # practice there are DAP implementations that do not send the initialized event until post-launch, and all
773 # adapters seem to accept us not waiting for the initialized event, so ignoring it gives maximum compatibility.
774 launch_req_id = self.send_message(self.make_request("launch", launch_request))
775
776 # Wait for the initialized event; for LLDB, this will be sent after the launch request has been processed;
777 # for other debuggers, it will have been sent some time after the initialize response was sent.
778 # NB: In all currently known cases this timeout is never hit because the initialized event is usually received
779 # almost immediately after either the initialize response or the launch request/response, and otherwise this
780 # timeout is long enough for any internal debugger timeout to be hit, and so if this gets hit it probably means
781 # the debugger is hanging.
782 initialize_timeout = Timeout(60)
783 while self._proc.poll() is None and not self._debugger_state.initialized:
784 if initialize_timeout.timed_out():
785 raise TimeoutError(
786 "Timed out while waiting for initialized event from DAP"
787 )
788 time.sleep(0.01)
789
790 # Set breakpoints after receiving launch response but before configurationDone.
791 self._flush_breakpoints()
792
793 # Send configurationDone to allow the process to start running.
794 config_done_req_id = self.send_message(self.make_request("configurationDone"))
795 launch_response = self._await_response(launch_req_id)
796 if not launch_response["success"]:
797 raise DebuggerException(
798 f"failure launching debugger: \"{launch_response['body']['error']['format']}\""
799 )
800 config_done_response = self._await_response(config_done_req_id)
801 assert config_done_response["success"]
802
803 # Wait for the process to launch and obtain a thread ID.
804 while self._debugger_state.thread is None or not self._debugger_state.launched:
805 time.sleep(0.001)
806
807 # LLDB has unique stepping behaviour w.r.t. breakpoints that needs to be handled after completing a step, so we use
808 # an overridable hook to enable debugger-specific behaviour.
809 def _post_step_hook(self):
810 """Hook to be executed after completing a step request."""
811
812 def _step(self, step_request_string):
813 self._flush_breakpoints()
814 step_req_id = self.send_message(
815 self.make_request(
816 step_request_string, {"threadId": self._debugger_state.thread}
817 )
818 )
819 response = self._await_response(step_req_id)
820 if not response["success"]:
821 raise DebuggerException(
822 f"failed to perform debugger action: '{step_request_string}'"
823 )
824 # If we've "stepped" to a breakpoint, then continue to hit the breakpoint properly.
825 # NB: This is an issue that only seems relevant to LLDB, but is also harmless outside of LLDB; if it turns out
826 # to cause issues for other debuggers, we can move it to a post-step hook.
827 while self._debugger_state.is_running:
828 time.sleep(0.001)
829 self._post_step_hook()
830
831 def step_in(self):
832 self._step("stepIn")
833
834 def step_next(self):
835 self._step("next")
836
837 def step_out(self):
838 self._step("stepOut")
839
840 def go(self) -> ReturnCode:
841 self._flush_breakpoints()
842 continue_req_id = self.send_message(
843 self.make_request("continue", {"threadId": self._debugger_state.thread})
844 )
845 response = self._await_response(continue_req_id)
846 if not response["success"]:
847 raise DebuggerException("failed to continue")
848 # Assuming the request to continue succeeded, we still need to wait to receive an event back from the debugger
849 # indicating that we have successfully resumed.
850
851 def _get_step_info(self, watches, step_index):
852 assert (
853 not self._debugger_state.is_running
854 ), "Cannot get step info while debugger is running!"
855 trace_req_id = self.send_message(
856 self.make_request("stackTrace", {"threadId": self._debugger_state.thread})
857 )
858 trace_response = self._await_response(trace_req_id)
859 if not trace_response["success"]:
860 raise DebuggerException("failed to get stack frames")
861 stackframes = trace_response["body"]["stackFrames"]
862
863 frames = []
864 state_frames = []
865
866 for idx, stackframe in enumerate(stackframes):
867 # FIXME: No source, skip the frame! Currently I've only observed this for frames below main, so we break
868 # here; if it happens elsewhere, then this will break more stuff and we'll come up with a better solution.
869 if (
870 stackframe.get("source") is None
871 or stackframe["source"].get("path") is None
872 ):
873 break
874 loc_dict = {
875 "path": stackframe["source"]["path"],
876 "lineno": stackframe["line"],
877 "column": stackframe["column"],
878 }
879 loc = LocIR(**loc_dict)
880 valid_loc_for_watch = loc.path and os.path.exists(loc.path)
881 frame = FrameIR(
882 function=self._sanitize_function_name(stackframe["name"]),
883 is_inlined=stackframe["name"].startswith("[Inline Frame]"),
884 loc=loc,
885 )
886
887 # We skip frames that are below "main", since we do not expect those to be user code.
888 fname = frame.function or "" # pylint: disable=no-member
889 if any(name in fname for name in self.frames_below_main):
890 break
891
892 frames.append(frame)
893
894 state_frame = StackFrame(
895 function=frame.function,
896 is_inlined=frame.is_inlined,
897 location=SourceLocation(**loc_dict),
898 watches={},
899 )
900 if valid_loc_for_watch:
901 for expr in map(
902 # Filter out watches that are not active in the current frame,
903 # and then evaluate all the active watches.
904 lambda watch_info, idx=idx: self.evaluate_expression(
905 watch_info.expression, idx
906 ),
907 filter(
908 lambda watch_info, idx=idx, line_no=loc.lineno, loc_path=loc.path: watch_is_active(
909 watch_info, loc_path, idx, line_no
910 ),
911 watches,
912 ),
913 ):
914 state_frame.watches[expr.expression] = expr
915 state_frames.append(state_frame)
916
917 if len(frames) == 1 and frames[0].function is None:
918 frames = []
919 state_frames = []
920
921 reason = self._translate_stop_reason(self._debugger_state.stopped_reason)
922
923 return StepIR(
924 step_index=step_index,
925 frames=frames,
926 stop_reason=reason,
927 program_state=ProgramState(state_frames),
928 )
929
930 @property
931 def is_running(self):
932 return self._debugger_state.is_running
933
934 @property
935 def is_finished(self):
936 return self._debugger_state.is_finished
937
938 @property
939 def frames_below_main(self):
940 pass
941
942 @staticmethod
943 @abc.abstractmethod
944 def _evaluate_result_value(expression: str, result_string: str) -> ValueIR:
945 """For the result of an "evaluate" message, return a ValueIR. Implementation must be debugger-specific."""
946
947 def evaluate_expression(self, expression, frame_idx=0) -> ValueIR:
948 # The frame_idx passed in here needs to be translated to the debug adapter's internal frame ID.
949 dap_frame_id = self._debugger_state.frame_map[frame_idx]
950 eval_req_id = self.send_message(
951 self.make_request(
952 "evaluate",
953 {
954 "expression": expression,
955 "frameId": dap_frame_id,
956 "context": "watch",
957 },
958 )
959 )
960 eval_response = self._await_response(eval_req_id)
961 result: str = ""
962 if not eval_response["success"]:
963 if eval_response["body"].get("error", None):
964 result = eval_response["body"]["error"]["format"]
965 elif eval_response["message"]:
966 result = eval_response["message"]
967 else:
968 result = "<unable to evaluate expression>"
969 else:
970 result = eval_response["body"]["result"]
971 type_str = eval_response["body"].get("type")
972
973 return self._evaluate_result_value(expression, result, type_str)