Aiegdb Console

name: aiegdb-console description: PRECEDENCE - this skill alone owns "what is the exact aie_exec command string?"; other skills name commands, this one is authoritative on spelling, arguments and scope. Read while COMPOSING an mcp__aiegdb__aie_exec call, or after one errored, hung, came back empty, or was rejected as a live TUI. Your always-loaded system prompt shows two WRONG forms: bd <id> (bd takes NO argument; the id is silently ignored) and target channel DIR N (rejected - it is one token, target channel mm2s0). Gives the partition -> tile -> channel scope model and what each level auto-injects (phys_col = col + startcol and row at tile scope, direction and channel number at channel scope), the per-scope verb/alias/argument tables straight from aiegdb.COMMAND_SPEC, which raw aiedbg passthroughs are refused (show cores, show dmaevent, show dmastatus) or monopolise the JTAG link (scan), the places event prints no decode at all (shim tile scope; shim channels beyond ch0/ch1), and the INTRUSIVE writers to ask the user about before firing: dma counter setup [finished|started], the only COMMAND_SPEC entry flagged intrusive=True (it reg-writes CONTROL0, 0x11000 core / 0x31000 shim), and any passthrough whose name starts with write, e.g. reg write. Syntax only: whether you may believe the answer is session-provenance's, what the decoded numbers mean is dma-stall-triage's, what the IPC simulator additionally blocks is simulator-vs-hardware's.

Driving aiegdb through aie_exec

Source of truth: src/tool/debug/aiegdb.py (COMMAND_SPEC, _dispatch, _tile_cmd, _channel_cmd) and src/tool/debug/aiemcp.py (_run, _needs_hw, _session_refusal).

Scope model

One long-lived AieGdb instance lives inside the MCP server, so scope persists across tool calls. Three nested levels; the returned "scope" field is the prompt:

partition(startcol=N)>                     nothing decoded here — raw aiedbg only
partition(startcol=N)/tile(0,3)>           target tile 0 3
partition(startcol=N)/tile(0,3)/mm2s0>     target channel mm2s0

• partition — holds startcol, device, aie_version, target. COMMAND_SPEC["partition"] is empty: every non-navigation verb here is forwarded verbatim to the aiedbg binary with explicit col/row.
• tile — target tile <col> <row> (col/row are logical). Decoded commands auto-inject phys_col = col + startcol and row (AieGdb.phys_col). row == 0 is typed shim, else core.
• channel — target channel <dir_ch>, <dir_ch> matching ^(mm2s|s2mm)\d+$. Direction and channel number are auto-injected on top of col/row, so dma status / bd / event need no args.

Navigation, valid at every scope (COMMAND_SPEC["universal"]):

tile(0,3) parenthesised forms work — _expand_parens rewrites them to tile 0 3. A bare mm2s0 at tile scope also selects the channel.

Tile-scope commands (COMMAND_SPEC["tile"])

reg read OFF, mem read ADDR LEN and callstack show|layers|stream are passthrough here with col/row auto-filled. reg write OFF VAL is also passthrough with col/row auto-filled and WRITES HARDWARE — ask the user before issuing it (see Intrusive below). callstack also gets --work-dir injected and, only when you do not supply col/row yourself, work_row = max(0, row - 3) appended — Work/ directory coordinates, not schedule rows (aiegdb.py _tile_cmd, the has_coords check).

Channel-scope commands (COMMAND_SPEC["channel"])

Intrusive — do not run casually

Only one entry in COMMAND_SPEC carries intrusive: True: dma counter setup. It reg writes CONTROL0 — 0x11000 on core tiles (PERF_OFFSETS["core_mem"]["ctrl0"]) or 0x31000 on shim (PERF_OFFSETS["shim_pl"]["ctrl0"]) — packing the event id into bits[6:0] and bits[14:8] so CNT0 start == stop == that event, and it perturbs the running design. The counter value registers are 0x11020/0x11024 (core mem) and 0x31020/0x31024 (shim PL); plain dma counter only reads those plus CONTROL0, and is read-only.

Passthrough commands are auto-marked intrusive when any word of the name starts with write (_parse_aiedbg_help: intrusive=any(t.startswith("write") ...)), e.g. reg write, reg write-mmio. Ask the user before firing any of these.

Passthrough (raw aiedbg) — and what will break

Anything aiegdb does not decode is forwarded to the aiedbg binary. The passthrough list is discovered at runtime from aiedbg --help (discover_aiedbg_spec), so run aie_exec("?") to see what this install actually has rather than assuming.

• Blocking live TUIs are refused. aiemcp sets gdb.no_tui = True, so _blocked_tui rejects show cores, show dmaevent, show dmastatus (and anything aiedbg --help describes as "Real-time …"/"Live …"). Do not retry them; use the UI grid overlay.
• scan ... is array-wide and can monopolise the JTAG link (slow); prefer target tile C R + a scoped read.
• Passthrough has a 120 s timeout (AIEGDB_PASSTHROUGH_TIMEOUT).
• On the simulator backend (AIEMCP_BACKEND=simulator) _patch_gdb_for_simulator replaces _passthrough with a stub: reg read, mem read, scan are unavailable and only decoded commands (dma, pc, event, channels, bd) work, via the IPC socket. Check mcp__debugui__get_backend_status first.

Session gate — when you get {"refused": true}

_run() calls _session_refusal(line) before touching the device. _needs_hw(line) looks at the first token only; these verbs never need a board (_NO_HW_VERBS):

target  tar  tile  channel  up  ..  top  where  info  pwd  set
help  ?  commands  cmds  spec  exit  quit  q  channels  chans

Exception coded explicitly: tile list (verb tile, arg list) is a passthrough and is gated. Note also that a bare mm2s0 (channel-select shortcut) is not in the set, so it is gated even though it only navigates — use target channel mm2s0 instead.

Everything else is gated on backend_status.json > session.authorized, written by the daemon (DebugState.session_state). Authorized means the user pressed Connect (connected), Run (ran), or Open Current Session (attached). If not authorized, aie_exec returns:

{"output": "REFUSED: no board session ...", "scope": "...", "refused": true, "session": {...}}

When you see refused: true: nothing was read. Do not describe, infer, or guess board state, and do not fall back to the applog as if it were this run. Tell the user to press Connect / Run / Open Current Session. (If backend_status.json has no session key — aiemcp launched standalone — the gate is skipped and commands proceed.)

Worked navigation

Everything that touches a register needs an authorized session; only where, ?, target ..., channels, up and top are session-free (_NO_HW_VERBS).

aie_exec("where")                    # scope + startcol/device/target, no board needed
aie_exec("?")                        # commands valid right here
aie_exec("target tile 0 3")          # -> "scope -> partition(startcol=N)/tile(0,3)  (phys_col=..., row=3)"
aie_exec("channels")                 # JSON-only: which channels this tile has
aie_exec("status")                   # core enable/reset/stall   [needs session]
aie_exec("pc")                       # PC -> file:line            [needs session]
aie_exec("target channel mm2s0")
aie_exec("event")                    # started / finished / stuck verdict   [needs session]
aie_exec("bd")                       # BD chain + live HW lengths           [needs session]
aie_exec("up")                       # back to tile scope
aie_exec("top")                      # back to partition

Decoded commands append a [registers read] { … } appendix listing each address and raw value — quote those when reporting, they are the ground truth behind the decode.