Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ All notable changes to the Simics Target Debug extension will be documented here

## [Unreleased]

### Added

- The Call Stack view shows the run control context hierarchy: each context
with child contexts, such as a process of the Linux tracker, is a nested
session with its threads. Turn it off with `"callStackHierarchy": false`.
`"callStackCompact": false` gives every context a row of its own.
Containers with a single thread, such as most processes, show the thread in
the session above.

### Changed

- In TCF Launch Configurations, the Start, Duplicate and Delete buttons
Expand Down
88 changes: 85 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ and translates DAP requests to TCF commands:
| VS Code (DAP) | TCF |
|--------------------------|------------------------------------------------------------|
| attach | TCP connection + `Locator.Hello` |
| threads | `RunControl` contexts with `HasState` |
| threads | `RunControl` contexts with `HasState`, grouped in a session per container context, see below |
| pause / continue | `RunControl.suspend` / `RunControl.resume` |
| step over / into / out | `RunControl.resume` with a step mode, see below |
| stopped / continued | `contextSuspended`, `containerSuspended`, `contextResumed`, `containerResumed` events |
Expand Down Expand Up @@ -66,6 +66,81 @@ resume or step.

### Call stack

The Call Stack view shows the parts of the target that can run and be
stopped: processors and, with OS awareness, the processes and threads of the
operating system. They are shown as a tree that follows the structure of the
target. Parts with several threads, such as a board with several CPUs, an OS
awareness tracker or a multi-threaded process, are shown as groups that can
be expanded. Expand a thread to see its call stack.

To keep the tree short:

- Only parts with at least two threads get a group. A part with a single
thread, such as most Linux processes, gets no group: its thread is listed
in the group above.
- A thread listed in a group above is named by the parts in between, so
thread `worker` of process `p3` is listed as `p3.worker`. A repeated name,
such as process `init` with thread `init`, is shown once.
- If a group would hold only one thread next to other groups, that thread
gets a row of its own, with its call stack right below it.

In a group, the threads are listed first, then the single threads with rows
of their own, then the other groups, each in the order of the target.

For example, take this target with a Linux OS awareness tracker, with
simplified names:

```text
Linux
├── Kernel
│ ├── Other ── core[0][0]
│ ├── Idle ──┬── core[0][0]
│ │ └── core[1][0]
│ └── Threads ──┬── kthreadd
│ └── kworker/0:0
└── Userspace ──┬── init ── init
├── rc ── rc
└── udevd ── udevd
```

The Call Stack view shows it like this:

```text
Linux group, in the row of the debug configuration
├── Kernel group
│ ├── Other.core[0][0] single thread with a row of its own
│ ├── Idle group
│ │ ├── core[0][0] thread
│ │ └── core[1][0] thread
│ └── Threads group
│ ├── kthreadd thread
│ └── kworker/0:0 thread
└── Userspace group
├── init thread
├── rc thread
└── udevd thread
```

`Other` and the processes in `Userspace` have a single thread each, so they
get no group. The thread of `Other` is next to the groups `Idle` and
`Threads`, so it gets a row of its own.

Groups come and go as processes and threads start and end. All groups share
the breakpoints and the Debug Console. Stopping or restarting any of them
stops or restarts the whole debug session.

Two options change the layout. You find them under **Advanced** in the
launch configurations editor:

- `"callStackHierarchy": false` shows no groups. All threads are listed
directly under the debug configuration, named by all the parts above them,
like `board.cpu0`. In the example, the threads are named
`Linux.Kernel.Idle.core[0][0]`, `Linux.Userspace.init.init` and so on.
- `"callStackCompact": false` gives every group a row of its own. By default,
a group that is alone in its parent shares the parent's row and shows its
own name only, like `Linux` in the example. With `false`, the name of the
debug configuration gets a row of its own above `Linux`.

The call stack of a suspended thread comes from the `StackTrace` service. VS
Code first loads the top frame and then the rest in pages ("Load More Stack
Frames"), which uses `getChildrenRange`; agents without it fall back to
Expand Down Expand Up @@ -392,6 +467,8 @@ Configuration attributes:
| `traceTcf` | `false` | Log TCF messages to Output › Simics Target Debug |
| `traceTcfSilence` | see below | TCF messages left out of the `traceTcf` log |
| `disassemblyFunctionHeaders` | `true` | Function header rows in the Disassembly view |
| `callStackHierarchy` | `true` | A nested session per container context in the Call Stack view |
| `callStackCompact` | `true` | Contexts that are the only child share a row with their parent |

### TCF trace

Expand Down Expand Up @@ -448,8 +525,8 @@ buttons in the editor title switch between the form and the text of
- The fields come from `configurationAttributes` in `package.json`, so new
attributes appear without changes to the form. Of VS Code's own options
only `internalConsoleOptions` (when to open the Debug Console) is shown,
under **Advanced** at the end, with `connectTimeout`,
`disassemblyFunctionHeaders`, `traceTcf` and `traceTcfSilence`. The Simics console options
under **Advanced** at the end, with `connectTimeout`, `callStackHierarchy`,
`callStackCompact`, `disassemblyFunctionHeaders`, `traceTcf` and `traceTcfSilence`. The Simics console options
and **Stay in Console** are under **Console**, just before **Advanced**.
Others, like
`preLaunchTask`, are listed under **Other Attributes** when set, and can be
Expand Down Expand Up @@ -660,6 +737,11 @@ on the agent (for example with `add-pathmap-entry`).
debug type.
- `src/tcfDebugSession.ts` – DAP implementation (no `vscode` dependency, so it
can also be run as a standalone debug adapter later).
- `src/contextSession.ts` – adapter of the child sessions that show the
threads of a container context; passes requests on to the root session's
adapter.
- `src/contextSessionManager.ts` – starts the child sessions in VS Code and
maps them to their root session for the extension's views and commands.
- `src/breakpointManager.ts` – keeps the agent's breakpoint table in sync with
VS Code.
- `src/variables.ts` – local variables and expressions through the
Expand Down
10 changes: 10 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -917,6 +917,16 @@
"type": "boolean",
"description": "Show a header row with source file, line and name above the first instruction of each function in the Disassembly view. Needs the agent's Symbols service and the setting debug.disassemblyView.showSourceCode. Turn off to save the symbol lookups.",
"default": true
},
"callStackHierarchy": {
"type": "boolean",
"description": "Show the run control context hierarchy in the Call Stack view: each context with child contexts and two or more threads (for example a multi-threaded process of an OS awareness tracker) becomes a nested session that holds its threads. Turn off to list all threads directly under the debug session, with their full names.",
"default": true
},
"callStackCompact": {
"type": "boolean",
"description": "With callStackHierarchy, let VS Code show a context in one row with its parent when it is the parent's only child. The row shows the name of the innermost context only. Turn off to give every context a row of its own, below a row for the debug session.",
"default": true
Comment thread
emanuelen5 marked this conversation as resolved.
Resolved
}
}
}
Expand Down
93 changes: 93 additions & 0 deletions src/contextSession.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
import { DebugSession, InitializedEvent, Response, TerminatedEvent } from "@vscode/debugadapter";
import { DebugProtocol } from "@vscode/debugprotocol";
import { ContextSessionLink, ContextSessionSink, TCF_CAPABILITIES } from "./tcfDebugSession";

/** Connects a child session to its group in the root adapter, undefined if the group is gone. */
export type ContextSessionConnector = (sink: ContextSessionSink) => ContextSessionLink | undefined;

/**
* Debug adapter of a child session that shows the threads of one container
* context (see ContextSessionHost). The root adapter does the work: thread,
* frame and variable IDs are the root's, so requests are passed on as they
* are. Breakpoints are only planted by the root session.
*/
export class TcfContextSession extends DebugSession implements ContextSessionSink {
private link: ContextSessionLink | undefined;
private terminated = false;

constructor(private readonly connect: ContextSessionConnector) {
super();
}

terminate(): void {
this.link = undefined;
if (!this.terminated) {
this.terminated = true;
this.sendEvent(new TerminatedEvent());
}
}

override sendEvent(event: DebugProtocol.Event): void {
if (event.event === "stopped") {
// The IDs are the root session's. Without them VS Code finds the
// hit breakpoints by the location of the top frame.
const body = { ...(event as DebugProtocol.StoppedEvent).body };
delete body.hitBreakpointIds;
event = { ...event, body };
}
super.sendEvent(event);
}

protected override dispatchRequest(request: DebugProtocol.Request): void {
const response: DebugProtocol.Response = new Response(request);
switch (request.command) {
case "initialize":
response.body = { ...TCF_CAPABILITIES };
this.sendResponse(response);
return;
case "attach":
case "launch":
this.link = this.connect(this);
this.sendResponse(response);
if (this.link) {
this.sendEvent(new InitializedEvent());
} else {
this.terminate();
}
return;
case "configurationDone":
this.sendResponse(response);
this.link?.configured();
return;
case "threads":
response.body = { threads: this.link?.threads() ?? [] };
this.sendResponse(response);
return;
case "setBreakpoints":
case "setFunctionBreakpoints":
case "setInstructionBreakpoints":
case "setDataBreakpoints":
// No entries, so VS Code keeps the root session's state for
// each breakpoint.
response.body = { breakpoints: [] };
this.sendResponse(response);
return;
case "setExceptionBreakpoints":
this.sendResponse(response);
return;
case "disconnect":
case "terminate":
this.link?.disconnect();
this.link = undefined;
this.terminated = true;
this.sendResponse(response);
return;
}
const link = this.link;
if (!link) {
this.sendErrorResponse(response, 4, "The debug session has ended");
return;
}
void link.forward(request).then((r) => this.sendResponse({ ...r, seq: 0, request_seq: request.seq }));
}
}
Loading