[Lldb-commits] [lldb] [lldb-dap] Document lldb-dap extensions (PR #233529)

[Kazu Hirata via lldb-commits]

================
@@ -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'.
----------------
kazutakahirata wrote:

Nit: May I suggest a closing single quote and a period after `e.g`?

```suggestion
   * The `lldb::SymbolType`, e.g. 'Code', 'Trampoline', 'Data'.
```

https://github.com/llvm/llvm-project/pull/233529