blob: 4e576ee03f95fb08c1ff492abe4af8c89df273b0 [file]
# Copyright 2026 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
from __future__ import annotations
from typing import TYPE_CHECKING
from daemon.handlers.frame_utils import resolve_frame_id
from pydap.models import DataBreakpointInfoArguments
from shared.protocol.base import Response
from shared.protocol.tracepoint import (
COMMAND_NAME,
TracepointInfo,
TracepointRequest,
TracepointResponse,
)
from zxdb_dap.models import ZxdbTracepointSpec, ZxdbTracepointWatchSpec
__all__ = ["COMMAND_NAME", "handle", "sync_tracepoints_with_dap"]
if TYPE_CHECKING:
from daemon.daemon import Daemon
_MAX_DAP_INT64 = (1 << 63) - 1
def _parse_hex_address(expr: str) -> tuple[int | None, str | None]:
"""Parses a 0x-prefixed hex address within signed 64-bit DAP bounds."""
cleaned = expr.strip()
lower = cleaned.lower()
if lower.startswith("-0x"):
return None, f"Watch address '{cleaned}' must be non-negative"
if not lower.startswith("0x"):
return None, None
try:
addr = int(cleaned, 16)
except ValueError:
return None, None
if addr < 0 or addr > _MAX_DAP_INT64:
return (
None,
f"Watch address '{cleaned}' exceeds signed 64-bit integer range",
)
return addr, None
def _matches_code_location(tp: TracepointInfo, req: TracepointRequest) -> bool:
"""Returns True if tp has the same function or file:line target as req."""
if req.function is not None and tp.function == req.function:
return True
return (
req.file is not None
and req.line is not None
and tp.file == req.file
and tp.line == req.line
)
def _matches_target_location(
tp: TracepointInfo, req: TracepointRequest, data_id: str | None
) -> bool:
"""Returns True if tp has the same resolved target location as req.
The same watch expression resolves to a different dataId in another
thread, frame, or process, so watch tracepoints match on the resolved
dataId as well as the expression text.
"""
if _matches_code_location(tp, req):
return True
return (
req.watch is not None
and tp.watch == req.watch
and tp.data_id == data_id
)
def _matches_request(tp: TracepointInfo, req: TracepointRequest) -> bool:
"""Returns True if tp matches req by ID when set, or by target text."""
if req.tracepoint_id is not None:
return tp.id == req.tracepoint_id
if _matches_code_location(tp, req):
return True
return req.watch is not None and tp.watch == req.watch
def _format_tracepoint_location(req: TracepointRequest) -> str:
"""Formats a human-readable location label for a tracepoint request."""
if req.function is not None:
return req.function
if req.watch is not None:
return f"watch:{req.watch}"
return f"{req.file}:{req.line}"
def _dap_enabled(tp: TracepointInfo, rearm: bool) -> bool | None:
"""Returns the enabled value to send for tp in a zxdb.SetTracepoints sync.
Only explicit user actions send a value. A user disable sends False, and
rearm sends True. Otherwise the field is omitted so that the server keeps
its own auto-disabled state, even when the daemon has not yet processed
the zxdb.Tracepoint event that reported it.
"""
if rearm:
return True
if not tp.enabled and not tp.auto_disabled:
return False
return None
def _build_dap_spec(
tp: TracepointInfo, rearm: bool = False
) -> ZxdbTracepointSpec:
"""Converts a daemon TracepointInfo into a ZxdbTracepointSpec wire model."""
watch_spec: ZxdbTracepointWatchSpec | None = None
if tp.watch is not None:
address_val, _ = _parse_hex_address(tp.watch)
watch_spec = ZxdbTracepointWatchSpec(
data_id=tp.data_id,
address=address_val if tp.data_id is None else None,
expression=tp.watch,
byte_size=tp.size,
access_type=tp.access_type or "write",
)
return ZxdbTracepointSpec(
id=tp.id,
function=tp.function,
file=tp.file,
line=tp.line,
watch=watch_spec,
condition=tp.condition,
expressions=list(tp.expressions) if tp.expressions else None,
max_matching_frames=tp.max_matching_frames,
max_hits=tp.max_hits,
frame="frame" in tp.capture,
backtrace="backtrace" in tp.capture,
raw_backtrace=tp.raw_backtrace,
locals="locals" in tp.capture,
registers="registers" in tp.capture,
enabled=_dap_enabled(tp, rearm),
)
async def sync_tracepoints_with_dap(
daemon: Daemon, rearm_id: int | None = None
) -> None:
"""Synchronizes daemon tracepoints with the zxdb DAP server.
rearm_id names the tracepoint that the user explicitly set or enabled in
this request. The server re-enables it even if it was auto-disabled.
"""
specs = [
_build_dap_spec(tp, rearm=tp_id == rearm_id)
for tp_id, tp in daemon.tracepoints.items()
]
dap_resp = await daemon.dap_client.zxdb_set_tracepoints(specs)
info_by_id = {info.id: info for info in dap_resp.body.tracepoints}
for tp_id, tp in daemon.tracepoints.items():
if (info := info_by_id.get(tp_id)) is not None:
tp.verified = info.verified
tp.hit_count = info.hit_count
tp.enabled = info.enabled
tp.auto_disabled = info.auto_disabled
tp.message = info.message
async def _handle_clear(daemon: Daemon) -> Response[TracepointResponse]:
"""Deletes all tracepoints and syncs an empty list with the DAP server."""
removed = dict(daemon.tracepoints)
daemon.tracepoints.clear()
try:
await sync_tracepoints_with_dap(daemon)
except Exception as e:
daemon.tracepoints.update(removed)
return Response(
success=False,
message=f"Failed to sync tracepoints with DAP: {e}",
)
return Response(success=True, body=TracepointResponse(tracepoints=[]))
async def _handle_delete(
daemon: Daemon, req: TracepointRequest
) -> Response[TracepointResponse]:
"""Deletes tracepoints matching req and syncs with the DAP server."""
to_remove = [
tp_id
for tp_id, tp in daemon.tracepoints.items()
if _matches_request(tp, req)
]
if not to_remove:
return Response(
success=False,
message="No matching tracepoint found to delete.",
)
if req.watch is not None and len(to_remove) > 1:
ids = ", ".join(str(tp_id) for tp_id in to_remove)
return Response(
success=False,
message=(
f"Multiple watch tracepoints match '{req.watch}' ({ids})."
" Delete by tracepoint ID."
),
)
removed = {tp_id: daemon.tracepoints.pop(tp_id) for tp_id in to_remove}
try:
await sync_tracepoints_with_dap(daemon)
except Exception as e:
daemon.tracepoints.update(removed)
return Response(
success=False,
message=f"Failed to sync tracepoints with DAP: {e}",
)
return Response(
success=True,
body=TracepointResponse(tracepoints=list(daemon.tracepoints.values())),
)
async def _handle_set_enabled(
daemon: Daemon, req: TracepointRequest
) -> Response[TracepointResponse]:
"""Enables or disables an existing tracepoint by ID and syncs with DAP."""
assert req.tracepoint_id is not None and req.enabled is not None
tp = daemon.tracepoints.get(req.tracepoint_id)
if tp is None:
return Response(
success=False,
message=f"Tracepoint {req.tracepoint_id} not found.",
)
prev_tp = tp.model_copy(deep=True)
if req.enabled:
if not tp.enabled:
tp.enabled = True
tp.auto_disabled = False
tp.hit_count = 0
else:
tp.enabled = False
tp.auto_disabled = False
rearm_id = req.tracepoint_id if req.enabled else None
try:
await sync_tracepoints_with_dap(daemon, rearm_id=rearm_id)
except Exception as e:
daemon.tracepoints[req.tracepoint_id] = prev_tp
return Response(
success=False,
message=f"Failed to sync tracepoints with DAP: {e}",
)
return Response(
success=True,
body=TracepointResponse(tracepoints=list(daemon.tracepoints.values())),
)
def _resolve_target_id(
daemon: Daemon, req: TracepointRequest, data_id: str | None
) -> tuple[int | None, str | None]:
"""Resolves or allocates the tracepoint ID while rejecting cross-ID collisions."""
loc_owner_id = next(
(
tp_id
for tp_id, tp in daemon.tracepoints.items()
if _matches_target_location(tp, req, data_id)
),
None,
)
if req.tracepoint_id is not None:
if loc_owner_id is not None and loc_owner_id != req.tracepoint_id:
loc = _format_tracepoint_location(req)
return (
None,
f"Location '{loc}' is already used by tracepoint {loc_owner_id}",
)
tp_id = req.tracepoint_id
daemon.next_tracepoint_id = max(daemon.next_tracepoint_id, tp_id + 1)
return tp_id, None
if loc_owner_id is not None:
return loc_owner_id, None
tp_id = daemon.next_tracepoint_id
daemon.next_tracepoint_id += 1
return tp_id, None
async def _resolve_watch_data_id(
daemon: Daemon, req: TracepointRequest
) -> tuple[str | None, str | None]:
"""Resolves the opaque server dataId for a watchpoint tracepoint."""
if req.watch is None:
return None, None
if (
req.tracepoint_id is not None
and (prev_tp := daemon.tracepoints.get(req.tracepoint_id)) is not None
and prev_tp.watch == req.watch
and prev_tp.data_id is not None
):
return prev_tp.data_id, None
hex_addr, hex_err = _parse_hex_address(req.watch)
if hex_err is not None:
return None, hex_err
if hex_addr is not None:
return None, None
if req.thread_id is None:
return (
None,
"thread_id (-t/--thread-id) is required when setting a watchpoint"
" tracepoint on an expression",
)
frame_id = await resolve_frame_id(daemon, req.thread_id, req.frame_index)
info_resp = await daemon.dap_client.data_breakpoint_info(
DataBreakpointInfoArguments(name=req.watch, frame_id=frame_id)
)
if not info_resp.body or not info_resp.body.data_id:
desc = (
info_resp.body.description
if info_resp.body and info_resp.body.description
else "no dataId returned"
)
return None, f"Cannot set watchpoint on '{req.watch}': {desc}"
return info_resp.body.data_id, None
async def _rollback_tracepoint(
daemon: Daemon, tp_id: int, prev_tp: TracepointInfo | None
) -> None:
"""Restores `prev_tp` (and re-syncs with DAP) or removes `tp_id` on failure."""
if prev_tp is not None:
daemon.tracepoints[tp_id] = prev_tp
await sync_tracepoints_with_dap(daemon)
else:
daemon.tracepoints.pop(tp_id, None)
async def _handle_set(
daemon: Daemon, req: TracepointRequest
) -> Response[TracepointResponse]:
"""Configures or updates a tracepoint and syncs with the DAP server."""
data_id, err = await _resolve_watch_data_id(daemon, req)
if err is not None:
return Response(success=False, message=err)
tp_id, id_err = _resolve_target_id(daemon, req, data_id)
if id_err is not None or tp_id is None:
return Response(success=False, message=id_err)
prev_existing = daemon.tracepoints.get(tp_id)
prev_tp = (
prev_existing.model_copy(deep=True)
if prev_existing is not None
else None
)
daemon.tracepoints[tp_id] = TracepointInfo(
id=tp_id,
location=_format_tracepoint_location(req),
file=req.file,
line=req.line,
function=req.function,
watch=req.watch,
data_id=data_id,
size=req.size,
access_type=req.access_type if req.watch is not None else None,
condition=req.condition,
expressions=list(req.expressions),
capture=list(req.capture),
raw_backtrace=req.raw_backtrace,
max_matching_frames=req.max_matching_frames,
max_hits=req.max_hits,
hit_count=prev_tp.hit_count if prev_tp is not None else 0,
enabled=True,
auto_disabled=False,
verified=False,
)
try:
await sync_tracepoints_with_dap(daemon, rearm_id=tp_id)
except Exception:
if prev_tp is not None:
daemon.tracepoints[tp_id] = prev_tp
else:
daemon.tracepoints.pop(tp_id, None)
raise
updated_tp = daemon.tracepoints[tp_id]
if not updated_tp.verified and updated_tp.message:
err_msg = updated_tp.message
await _rollback_tracepoint(daemon, tp_id, prev_tp)
return Response(success=False, message=err_msg)
return Response(
success=True,
body=TracepointResponse(tracepoints=list(daemon.tracepoints.values())),
)
async def handle(
daemon: Daemon, req: TracepointRequest
) -> Response[TracepointResponse]:
"""Handles a tracepoint request to list, manage, delete, or configure."""
if not daemon.zxdb_writer:
return Response(
success=False, message="Not connected to zxdb DAP server"
)
if req.list_all:
return Response(
success=True,
body=TracepointResponse(
tracepoints=list(daemon.tracepoints.values())
),
)
try:
if req.clear:
return await _handle_clear(daemon)
if req.enabled is not None:
return await _handle_set_enabled(daemon, req)
if req.delete:
return await _handle_delete(daemon, req)
return await _handle_set(daemon, req)
except Exception as e:
return Response(
success=False, message=f"Failed to manage tracepoint: {e}"
)