From ba8db4e401a14f027db6069828deec99338cbbf8 Mon Sep 17 00:00:00 2001 From: Colin Grant Date: Tue, 13 Feb 2024 09:33:57 -0700 Subject: [PATCH] Update README for current state --- README.md | 47 ++++++++++++++--------------------------------- 1 file changed, 14 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 1959773..d3131b5 100644 --- a/README.md +++ b/README.md @@ -4,43 +4,24 @@ This extension contributes a set of widgets for viewing memory in different ways ## Requirements -This extension must be used in conjunction with a Debug Adapter that implements a ReadMemoryRequest handler or alternative custom request that returns memory data. It has been tested against the [CDT-GDB Adapter](https://github.com/eclipse-cdt/cdt-gdb-adapter) used as the backend for the -[CDT-GDB VSCode](https://github.com/eclipse-cdt/cdt-gdb-vscode) plugin. This repository is configured to download that plugin as part of its build routine. -If you intend to use this extension with a different debug adapter, you may need to implement a custom -[`MemoryProvider`](./src/browser/memory-provider/memory-provider-service.ts) to handle any peculiarities of the requests and responses used by your adapter. +This extension must be used in conjunction with a Debug Adapter that implements a ReadMemoryRequest handler or alternative custom request that returns +memory data. It has been tested against the [CDT-GDB Adapter](https://github.com/eclipse-cdt/cdt-gdb-adapter) used as the backend for the +[CDT-GDB VSCode](https://github.com/eclipse-cdt/cdt-gdb-vscode) plugin. + +## The Memory Provider + +The primary entry point for the backend functionality of the plugin is the the [`MemoryProvider`](./src/plugin/memory-provider.ts) class. That class +has two primary functions: it handles requests that are specified by the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/), +and it instantiates custom handlers that can provide additional functionality depending on the capabilities of a given debug adapter. In order to +register custom capabilities, the [`AdapterRegistry`](./src/plugin/adapter-registry/adapter-registry.ts) matches debug types to objects implementing +the [`AdapterCapabilities`](./src/plugin/adapter-registry/adapter-capabilities.ts) interface. ## The Widgets ### Memory Widget -The basic [`MemoryWidget` class](./src/browser/memory-widget/memory-widget.ts) is a wrapper around two functional widgets, a `MemoryOptionsWidget` and -a`MemoryTableWidget`. The [`MemoryOptionsWidget`](./src/browser/memory-widget/memory-options-widget.tsx) is responsible for configuring the display -and fetching memory, and the [`MemoryTableWidget`](./src/browser/memory-widget/memory-table-widget.tsx) renders the memory according to the options +The basic [`MemoryWidget` class](./src/webview/components/memory-widget.ts) is a wrapper around two functional widgets, a `MemoryOptionsWidget` and +a`MemoryTableWidget`. The [`MemoryOptionsWidget`](./src/webview/components/options-widget.tsx) is responsible for configuring the display +and fetching memory, and the [`MemoryTableWidget`](./src/webview/components/table.tsx) renders the memory according to the options specified by the user in the `MemoryOptionsWidget`. The basic combination of these three classes offers variable highlighting, ascii display, and dynamic updating in response to events from the debug session, as well as the option to lock the view to ignore changes from the session. - -### Diff Widget - -The [`MemoryDiffWidget`](./src/browser/diff-widget/memory-diff-widget-types.ts) is an elaboration of the `MemoryWidget` type that allows side-by-side -comparison of the contents of two `MemoryWidgets`. - -### Register Widget - -Although it is not supported by the `cdt-gdb-vscode` debug adapter, the Debug Adapter Protocol supports including registers as a scope inside the -response to a variables request. The [`RegisterWidget`](./src/browser/register-widget/register-widget-types.ts) offers functionality to view and -manipulate those values when using a debug adapter that reports register contents. - -### Editable Widget - -Another feature not presently available from `cdt-gdb-vscode` but -[proposed for the Debug Adapter Protocol](https://github.com/microsoft/debug-adapter-protocol/issues/163) and available for implementation as a custom -request to a GDB backend is direct writing of memory by address. The -[`MemoryEditableTableWidget`](./src/browser/editable-widget/memory-editable-table-widget.tsx) adds UI functionality to allow users to modify values in -the table display and send them to a backend that supports that operation. - -## Using the Widgets - -The widgets are created by the [`MemoryWidgetManager`](./src/browser/utils/memory-widget-manager.ts), and modifying the `createNewMemoryWidget()` -method of that service allows you to change what kind of widget is instantiated and under what circumstances. The widgets get memory through the -[`MemoryProviderService`](./src/browser/memory-provider/memory-provider-service.ts), which delegates to implementations `MemoryProvider` interface -that are bound as `MemoryProvider` contributions.