[Lldb-commits] [lldb] [lldb-dap] Document lldb-dap extensions (PR #233529)
Ebuka Ezike via lldb-commits
lldb-commits at lists.llvm.org
Tue Oct 20 05:01:17 PDT 2026
https://github.com/da-viper updated https://github.com/llvm/llvm-project/pull/233529
>From 6a3a9153db5d15d908445f946e1ae11018ac4e08 Mon Sep 17 00:00:00 2001
From: Ebuka Ezike <e_ezike at apple.com>
Date: Fri, 16 Oct 2026 21:09:18 +0100
Subject: [PATCH 1/3] [lldb-dap] Document the DAP protocol extensions
lldb-dap extensions to the protocol has increased, there is no way
to know about this extensions without reading the source code or
looking at the logs.
Add documentation specifying the requests and the additional
properties lldb-dap adds to standard DAP messages.
---
lldb/docs/resources/lldbdap-contributing.md | 8 +-
lldb/docs/resources/lldbdap-extensions.md | 238 ++++++++++++++++++++
lldb/docs/use/lldbdap.md | 4 +
3 files changed, 247 insertions(+), 3 deletions(-)
create mode 100644 lldb/docs/resources/lldbdap-extensions.md
diff --git a/lldb/docs/resources/lldbdap-contributing.md b/lldb/docs/resources/lldbdap-contributing.md
index 16b9f263f7f1cd..de57239c7a4834 100644
--- a/lldb/docs/resources/lldbdap-contributing.md
+++ b/lldb/docs/resources/lldbdap-contributing.md
@@ -56,6 +56,7 @@ to LLDB's core in order to improve your debugging experience in VS Code.
### The Debug Adapter Protocol
The most relevant resources for the Debug Adapter Protocol are:
+
* [The overview](https://microsoft.github.io/debug-adapter-protocol/overview)
which provides a high-level introduction,
* the [human-readable specification](https://microsoft.github.io/debug-adapter-protocol/specification), and
@@ -71,7 +72,8 @@ inspiration from it. If not, consider opening an upstream issue.
To avoid naming collisions with potential future extensions of the Debug
Adapter protocol, all non-standard extensions should use the prefix
-`$__lldb_extension` in their JSON property names.
+`$__lldb_` in their JSON property names. See
+[LLDB-DAP Extensions](./lldbdap-extensions.md) for more details.
### Debugging the Debug Adapter Protocol
@@ -92,8 +94,8 @@ changed.
### Pre-requisites
-- Install a modern version of node (e.g. `v20.0.0`).
-- On VS Code, execute the command `Install 'code' command in PATH`. You need to
+* Install a modern version of node (e.g. `v20.0.0`).
+* On VS Code, execute the command `Install 'code' command in PATH`. You need to
do it only once. This enables the command `code` in the PATH.
### Packaging and installation
diff --git a/lldb/docs/resources/lldbdap-extensions.md b/lldb/docs/resources/lldbdap-extensions.md
new file mode 100644
index 00000000000000..e903d588687c19
--- /dev/null
+++ b/lldb/docs/resources/lldbdap-extensions.md
@@ -0,0 +1,238 @@
+# LLDB-DAP Extensions
+
+lldb-dap implements the
+[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/specification)
+(DAP). This page specifies what lldb-dap adds to the protocol, such as new requests and additional fields in protocol types.
+
+Conventions:
+
+- New requests should be prefixed with `__lldb_`.
+- Added properties on standard messages are prefixed with `$__lldb_`. If the field
+ is lldb specific (e.g. $__lldb_version ) else it plain names
+ (e.g. `compileUnitId`).
+
+## Custom Requests
+
+### CompileUnits Request
+
+The request is sent from the client to the debug adapter to list the compile
+units of a module. Use it with `compileUnitId` of a [`StackFrame`](#stackframe)
+and the `id` of a [`Module`](#module).
+
+```typescript
+interface CompileUnitsRequest extends Request {
+ command: 'compileUnits';
+
+ arguments: CompileUnitsArguments;
+}
+
+interface CompileUnitsArguments {
+ /**
+ * The UUID of the module.
+ */
+ moduleId: string;
+
+ /**
+ * The compile units to return. If empty or omitted, all compile units of
+ * the module are returned.
+ * @format uint32
+ */
+ compileUnitIds?: number[];
+}
+
+interface CompileUnitsResponse extends Response {
+ body: {
+ compileUnits: CompileUnit[];
+ };
+}
+
+interface CompileUnit {
+ /**
+ * The ID of the compile unit, unique within its module.
+ * @format uint32
+ */
+ id: number;
+
+ /**
+ * The path of the compile unit.
+ */
+ compileUnitPath: string;
+}
+```
+
+### ModuleSymbols Request
+
+The request is sent from the client to the debug adapter to list the symbols of
+a module. It is only available if the capability `supportsModuleSymbolsRequest`
+is true.
+
+```typescript
+interface ModuleSymbolsRequest extends Request {
+ command: '__lldb_moduleSymbols';
+
+ arguments: ModuleSymbolsArguments;
+}
+
+interface ModuleSymbolsArguments {
+ /**
+ * The UUID of the module.
+ */
+ moduleId: string;
+
+ /**
+ * The name of the module.
+ */
+ moduleName: string;
+
+ /**
+ * The index of the first symbol to return. If omitted starts at 0.
+ * @format uint32
+ */
+ startIndex?: number;
+
+ /**
+ * The number of symbols to return. If count is missing or 0, all variables
+ * are returned
+ * @format uint32
+ */
+ count?: number;
+}
+
+interface ModuleSymbolsResponse extends Response {
+ body: {
+ /**
+ * All symbols or range of symbols.
+ */
+ symbols: Symbol[];
+ };
+}
+
+interface Symbol {
+ /**
+ * The ID of the symbol.
+ * @format uint32
+ */
+ id: number;
+
+ /**
+ * The name of the symbol.
+ */
+ name: string;
+
+ /**
+ * The size of the symbol in bytes.
+ * @format uint64
+ */
+ size: number;
+
+ /**
+ * The symbol has debug information.
+ */
+ isDebug: boolean;
+
+ /**
+ * The symbol was synthesized by the debugger.
+ */
+ isSynthetic: boolean;
+
+ /**
+ * The symbol is visible outside of its module.
+ */
+ isExternal: boolean;
+
+ /**
+ * The `lldb::SymbolType`, e.g 'Code', 'Trampoline, 'Data'.
+ */
+ type: string;
+
+ /**
+ * The address of the symbol in the module file.
+ * @format uint64
+ */
+ fileAddress: number;
+
+ /**
+ * The address of the symbol in the process. Omitted if the module is not
+ * loaded.
+ * @format uint64
+ */
+ loadAddress?: number;
+}
+```
+
+## Requests with Additional Properties
+
+### Initialize Request
+
+```typescript
+interface InitializeRequestArguments {
+ /**
+ * Whether the adapter sources `lldbinit` files when initializing the
+ * debugger.
+ */
+ $__lldb_sourceInitFile?: boolean;
+}
+```
+
+```typescript
+interface InitializeResponse extends Response {
+ body?: Capabilities;
+}
+
+interface Capabilities {
+ /**
+ * The version of lldb same as (`version` command).
+ */
+ $__lldb_version?: string;
+
+ /**
+ * The debug adapter supports the `__lldb_moduleSymbols` request.
+ */
+ supportsModuleSymbolsRequest?: boolean;
+}
+```
+
+### ExceptionInfo Request
+
+```typescript
+interface ExceptionInfoResponse extends Response {
+ body: {
+ /**
+ * The raw JSON from `SBThread::GetStopReasonExtendedInfoAsJSON`.
+ */
+ $__lldb_stopReasonExtendedInfo?: any;
+
+ /**
+ * The raw JSON from `SBProcess::GetExtendedCrashInformation`.
+ */
+ $__lldb_extendedCrashInformation?: any;
+ };
+}
+```
+
+## Types with Additional Properties
+
+### Module
+
+```typescript
+interface Module {
+ /**
+ * The size of the module's debug information as a human readable string,
+ * e.g. '12.3 MB'.
+ */
+ debugInfoSize?: string;
+}
+```
+
+### StackFrame
+
+```typescript
+interface StackFrame {
+ /**
+ * The compile unit of the frame. Use with `moduleId` in the `compileUnits`
+ * request.
+ * @format uint32
+ */
+ compileUnitId?: number;
+}
+```
diff --git a/lldb/docs/use/lldbdap.md b/lldb/docs/use/lldbdap.md
index a4c151a2ff39c1..195617db5dd954 100644
--- a/lldb/docs/use/lldbdap.md
+++ b/lldb/docs/use/lldbdap.md
@@ -117,6 +117,10 @@ for more information.
For more information, see
[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/).
+`lldb-dap` also extends the protocol with a few LLDB specific requests and
+properties. They are specified in
+[LLDB-DAP Extensions](../resources/lldbdap-extensions.md).
+
### Debug Console
The Debug Console allows printing variables / expressions and executing lldb
>From 75bdd5a4bb84bea286338fa8864678ae1f343b07 Mon Sep 17 00:00:00 2001
From: Ebuka Ezike <e_ezike at apple.com>
Date: Mon, 19 Oct 2026 20:07:49 +0100
Subject: [PATCH 2/3] add review changes
---
lldb/docs/resources/lldbdap-extensions.md | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/lldb/docs/resources/lldbdap-extensions.md b/lldb/docs/resources/lldbdap-extensions.md
index e903d588687c19..ac96102deb006d 100644
--- a/lldb/docs/resources/lldbdap-extensions.md
+++ b/lldb/docs/resources/lldbdap-extensions.md
@@ -7,8 +7,8 @@ lldb-dap implements the
Conventions:
- New requests should be prefixed with `__lldb_`.
-- Added properties on standard messages are prefixed with `$__lldb_`. If the field
- is lldb specific (e.g. $__lldb_version ) else it plain names
+- Added properties on standard messages are prefixed with `$__lldb_` if the field
+ is LLDB-specific (e.g. `$__lldb_version`); otherwise, they use plain names
(e.g. `compileUnitId`).
## Custom Requests
@@ -91,8 +91,8 @@ interface ModuleSymbolsArguments {
startIndex?: number;
/**
- * The number of symbols to return. If count is missing or 0, all variables
- * are returned
+ * The number of symbols to return. If count is missing or 0, all symbols
+ * are returned.
* @format uint32
*/
count?: number;
@@ -141,7 +141,7 @@ interface Symbol {
isExternal: boolean;
/**
- * The `lldb::SymbolType`, e.g 'Code', 'Trampoline, 'Data'.
+ * The `lldb::SymbolType`, e.g. 'Code', 'Trampoline', 'Data'.
*/
type: string;
>From 3a6dfb23fb22da85cf11ee4d26e107c339f369cc Mon Sep 17 00:00:00 2001
From: Ebuka Ezike <e_ezike at apple.com>
Date: Tue, 20 Oct 2026 13:00:50 +0100
Subject: [PATCH 3/3] add review changes
---
lldb/docs/resources/lldbdap-extensions.md | 2 +-
lldb/docs/use/lldbdap.md | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/lldb/docs/resources/lldbdap-extensions.md b/lldb/docs/resources/lldbdap-extensions.md
index ac96102deb006d..1b5f6c9ea1a7dc 100644
--- a/lldb/docs/resources/lldbdap-extensions.md
+++ b/lldb/docs/resources/lldbdap-extensions.md
@@ -85,7 +85,7 @@ interface ModuleSymbolsArguments {
moduleName: string;
/**
- * The index of the first symbol to return. If omitted starts at 0.
+ * The index of the first symbol to return. If omitted, starts at 0.
* @format uint32
*/
startIndex?: number;
diff --git a/lldb/docs/use/lldbdap.md b/lldb/docs/use/lldbdap.md
index 195617db5dd954..f215e3a82541af 100644
--- a/lldb/docs/use/lldbdap.md
+++ b/lldb/docs/use/lldbdap.md
@@ -117,7 +117,7 @@ for more information.
For more information, see
[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/).
-`lldb-dap` also extends the protocol with a few LLDB specific requests and
+`lldb-dap` also extends the protocol with a few LLDB-specific requests and
properties. They are specified in
[LLDB-DAP Extensions](../resources/lldbdap-extensions.md).
More information about the lldb-commits
mailing list