1190 lines · c
1//===-- ProtocolTypes.h ---------------------------------------------------===//2//3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.4// See https://llvm.org/LICENSE.txt for license information.5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception6//7//===----------------------------------------------------------------------===//8//9// This file contains POD structs based on the DAP specification at10// https://microsoft.github.io/debug-adapter-protocol/specification11//12// This is not meant to be a complete implementation, new interfaces are added13// when they're needed.14//15// Each struct has a toJSON and fromJSON function, that converts between16// the struct and a JSON representation. (See JSON.h)17//18//===----------------------------------------------------------------------===//19 20#ifndef LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_REQUESTS_H21#define LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_REQUESTS_H22 23#include "Protocol/ProtocolBase.h"24#include "Protocol/ProtocolTypes.h"25#include "lldb/lldb-defines.h"26#include "lldb/lldb-types.h"27#include "llvm/ADT/DenseSet.h"28#include "llvm/ADT/StringMap.h"29#include "llvm/Support/JSON.h"30#include <chrono>31#include <cstdint>32#include <optional>33#include <string>34#include <vector>35 36namespace lldb_dap::protocol {37 38/// Arguments for `cancel` request.39struct CancelArguments {40 /// The ID (attribute `seq`) of the request to cancel. If missing no request41 /// is cancelled.42 ///43 /// Both a `requestId` and a `progressId` can be specified in one request.44 std::optional<int64_t> requestId;45 46 /// The ID (attribute `progressId`) of the progress to cancel. If missing no47 /// progress is cancelled.48 ///49 /// Both a `requestId` and a `progressId` can be specified in one request.50 std::optional<int64_t> progressId;51};52bool fromJSON(const llvm::json::Value &, CancelArguments &, llvm::json::Path);53 54/// Response to `cancel` request. This is just an acknowledgement, so no body55/// field is required.56using CancelResponse = VoidResponse;57 58/// Arguments for `disconnect` request.59struct DisconnectArguments {60 /// A value of true indicates that this `disconnect` request is part of a61 /// restart sequence.62 std::optional<bool> restart;63 64 /// Indicates whether the debuggee should be terminated when the debugger is65 /// disconnected. If unspecified, the debug adapter is free to do whatever it66 /// thinks is best. The attribute is only honored by a debug adapter if the67 /// corresponding capability `supportTerminateDebuggee` is true.68 std::optional<bool> terminateDebuggee;69 70 /// Indicates whether the debuggee should stay suspended when the debugger is71 /// disconnected. If unspecified, the debuggee should resume execution. The72 /// attribute is only honored by a debug adapter if the corresponding73 /// capability `supportSuspendDebuggee` is true.74 std::optional<bool> suspendDebuggee;75};76bool fromJSON(const llvm::json::Value &, DisconnectArguments &,77 llvm::json::Path);78 79/// Response to `disconnect` request. This is just an acknowledgement, so no80/// body field is required.81using DisconnectResponse = VoidResponse;82 83/// Features supported by DAP clients.84enum ClientFeature : unsigned {85 eClientFeatureVariableType,86 eClientFeatureVariablePaging,87 eClientFeatureRunInTerminalRequest,88 eClientFeatureMemoryReferences,89 eClientFeatureProgressReporting,90 eClientFeatureInvalidatedEvent,91 eClientFeatureMemoryEvent,92 /// Client supports the `argsCanBeInterpretedByShell` attribute on the93 /// `runInTerminal` request.94 eClientFeatureArgsCanBeInterpretedByShell,95 eClientFeatureStartDebuggingRequest,96 /// The client will interpret ANSI escape sequences in the display of97 /// `OutputEvent.output` and `Variable.value` fields when98 /// `Capabilities.supportsANSIStyling` is also enabled.99 eClientFeatureANSIStyling,100};101 102/// Format of paths reported by the debug adapter.103enum PathFormat : unsigned { ePatFormatPath, ePathFormatURI };104 105/// Arguments for `initialize` request.106struct InitializeRequestArguments {107 /// The ID of the debug adapter.108 std::string adapterID;109 110 /// The ID of the client using this adapter.111 std::optional<std::string> clientID;112 113 /// The human-readable name of the client using this adapter.114 std::optional<std::string> clientName;115 116 /// The ISO-639 locale of the client using this adapter, e.g. en-US or de-CH.117 std::optional<std::string> locale;118 119 /// Determines in what format paths are specified. The default is `path`,120 /// which is the native format.121 PathFormat pathFormat = ePatFormatPath;122 123 /// If true all line numbers are 1-based (default).124 std::optional<bool> linesStartAt1;125 126 /// If true all column numbers are 1-based (default).127 std::optional<bool> columnsStartAt1;128 129 /// The set of supported features reported by the client.130 llvm::DenseSet<ClientFeature> supportedFeatures;131 132 /// lldb-dap Extensions133 /// @{134 135 /// Source init files when initializing lldb::SBDebugger.136 std::optional<bool> lldbExtSourceInitFile;137 138 /// @}139};140bool fromJSON(const llvm::json::Value &, InitializeRequestArguments &,141 llvm::json::Path);142 143/// Response to `initialize` request. The capabilities of this debug adapter.144using InitializeResponse = std::optional<Capabilities>;145 146/// DAP Launch and Attach common configurations.147///148/// See package.json debuggers > configurationAttributes > launch or attach >149/// properties for common configurations.150struct Configuration {151 /// Specify a working directory to use when launching `lldb-dap`. If the debug152 /// information in your executable contains relative paths, this option can be153 /// used so that `lldb-dap` can find source files and object files that have154 /// relative paths.155 std::string debuggerRoot;156 157 /// Enable auto generated summaries for variables when no summaries exist for158 /// a given type. This feature can cause performance delays in large projects159 /// when viewing variables.160 bool enableAutoVariableSummaries = false;161 162 /// If a variable is displayed using a synthetic children, also display the163 /// actual contents of the variable at the end under a [raw] entry. This is164 /// useful when creating synthetic child plug-ins as it lets you see the165 /// actual contents of the variable.166 bool enableSyntheticChildDebugging = false;167 168 /// Enable language specific extended backtraces.169 bool displayExtendedBacktrace = false;170 171 /// Stop at the entry point of the program when launching or attaching.172 bool stopOnEntry = false;173 174 /// Optional timeout when waiting for the program to `runInTerminal` or175 /// attach.176 std::chrono::seconds timeout = std::chrono::seconds(30);177 178 /// The escape prefix to use for executing regular LLDB commands in the Debug179 /// Console, instead of printing variables. Defaults to a backtick. If it's an180 /// empty string, then all expression in the Debug Console are treated as181 /// regular LLDB commands.182 std::string commandEscapePrefix = "`";183 184 /// If non-empty, stack frames will have descriptions generated based on the185 /// provided format. See https://lldb.llvm.org/use/formatting.html for an186 /// explanation on format strings for frames. If the format string contains187 /// errors, an error message will be displayed on the Debug Console and the188 /// default frame names will be used. This might come with a performance cost189 /// because debug information might need to be processed to generate the190 /// description.191 std::optional<std::string> customFrameFormat;192 193 /// Same as `customFrameFormat`, but for threads instead of stack frames.194 std::optional<std::string> customThreadFormat;195 196 /// Specify a source path to remap "./" to allow full paths to be used when197 /// setting breakpoints in binaries that have relative source paths.198 std::string sourcePath;199 200 /// Specify an array of path re-mappings. Each element in the array must be a201 /// two element array containing a source and destination pathname. Overrides202 /// sourcePath.203 std::vector<std::pair<std::string, std::string>> sourceMap;204 205 /// LLDB commands executed upon debugger startup prior to creating the LLDB206 /// target.207 std::vector<std::string> preInitCommands;208 209 /// LLDB commands executed upon debugger startup prior to creating the LLDB210 /// target.211 std::vector<std::string> initCommands;212 213 /// LLDB commands executed just before launching/attaching, after the LLDB214 /// target has been created.215 std::vector<std::string> preRunCommands;216 217 /// LLDB commands executed just after launching/attaching, after the LLDB218 /// target has been created.219 std::vector<std::string> postRunCommands;220 221 /// LLDB commands executed just after each stop.222 std::vector<std::string> stopCommands;223 224 /// LLDB commands executed when the program exits.225 std::vector<std::string> exitCommands;226 227 /// LLDB commands executed when the debugging session ends.228 std::vector<std::string> terminateCommands;229 230 /// Path to the executable.231 ///232 /// *NOTE:* When launching, either `launchCommands` or `program` must be233 /// configured. If both are configured then `launchCommands` takes priority.234 std::string program;235 236 /// Target triple for the program (arch-vendor-os). If not set, inferred from237 /// the binary.238 std::string targetTriple;239 240 /// Specify name of the platform to use for this target, creating the platform241 /// if necessary.242 std::string platformName;243};244 245enum Console : unsigned {246 eConsoleInternal,247 eConsoleIntegratedTerminal,248 eConsoleExternalTerminal249};250 251/// lldb-dap specific launch arguments.252struct LaunchRequestArguments {253 /// Common lldb-dap configuration values for launching/attaching operations.254 Configuration configuration;255 256 /// If true, the launch request should launch the program without enabling257 /// debugging.258 bool noDebug = false;259 260 /// Launch specific operations.261 ///262 /// See package.json debuggers > configurationAttributes > launch >263 /// properties.264 /// @{265 266 /// LLDB commands executed to launch the program.267 ///268 /// *NOTE:* Either launchCommands or program must be configured.269 ///270 /// If set, takes priority over the 'program' when launching the target.271 std::vector<std::string> launchCommands;272 273 /// The program working directory.274 std::string cwd;275 276 /// An array of command line argument strings to be passed to the program277 /// being launched.278 std::vector<std::string> args;279 280 /// Environment variables to set when launching the program. The format of281 /// each environment variable string is "VAR=VALUE" for environment variables282 /// with values or just "VAR" for environment variables with no values.283 llvm::StringMap<std::string> env;284 285 /// If set, then the client stub should detach rather than killing the286 /// debuggee if it loses connection with lldb.287 bool detachOnError = false;288 289 /// Disable ASLR (Address Space Layout Randomization) when launching the290 /// process.291 bool disableASLR = true;292 293 /// Do not set up for terminal I/O to go to running process.294 bool disableSTDIO = false;295 296 /// Set whether to shell expand arguments to the process when launching.297 bool shellExpandArguments = false;298 299 /// Specify where to launch the program: internal console, integrated300 /// terminal or external terminal.301 Console console = eConsoleInternal;302 303 /// An array of file paths for redirecting the program's standard IO streams.304 std::vector<std::optional<std::string>> stdio;305 306 /// @}307};308bool fromJSON(const llvm::json::Value &, LaunchRequestArguments &,309 llvm::json::Path);310 311/// Response to `launch` request. This is just an acknowledgement, so no body312/// field is required.313using LaunchResponse = VoidResponse;314 315#define LLDB_DAP_INVALID_PORT -1316/// An invalid 'frameId' default value.317#define LLDB_DAP_INVALID_FRAME_ID UINT64_MAX318 319/// lldb-dap specific attach arguments.320struct AttachRequestArguments {321 /// Common lldb-dap configuration values for launching/attaching operations.322 Configuration configuration;323 324 /// Attach specific operations.325 ///326 /// See package.json debuggers > configurationAttributes > attach >327 /// properties.328 /// @{329 330 /// Custom commands that are executed instead of attaching to a process ID or331 /// to a process by name. These commands may optionally create a new target332 /// and must perform an attach. A valid process must exist after these333 /// commands complete or the `"attach"` will fail.334 std::vector<std::string> attachCommands;335 336 /// System process ID to attach to.337 lldb::pid_t pid = LLDB_INVALID_PROCESS_ID;338 339 /// Wait for the process to launch.340 bool waitFor = false;341 342 /// TCP/IP port to attach to a remote system. Specifying both pid and port is343 /// an error.344 int32_t gdbRemotePort = LLDB_DAP_INVALID_PORT;345 346 /// The hostname to connect to a remote system. The default hostname being347 /// used `localhost`.348 std::string gdbRemoteHostname = "localhost";349 350 /// Path to the core file to debug.351 std::string coreFile;352 353 /// Unique ID of an existing target to attach to.354 std::optional<lldb::user_id_t> targetId;355 356 /// ID of an existing debugger instance to use.357 std::optional<int> debuggerId;358 359 /// @}360};361bool fromJSON(const llvm::json::Value &, AttachRequestArguments &,362 llvm::json::Path);363 364/// Response to `attach` request. This is just an acknowledgement, so no body365/// field is required.366using AttachResponse = VoidResponse;367 368/// Arguments for `continue` request.369struct ContinueArguments {370 /// Specifies the active thread. If the debug adapter supports single thread371 /// execution (see `supportsSingleThreadExecutionRequests`) and the argument372 /// `singleThread` is true, only the thread with this ID is resumed.373 lldb::tid_t threadId = LLDB_INVALID_THREAD_ID;374 375 /// If this flag is true, execution is resumed only for the thread with given376 /// `threadId`.377 bool singleThread = false;378};379bool fromJSON(const llvm::json::Value &, ContinueArguments &, llvm::json::Path);380 381/// Response to `continue` request.382struct ContinueResponseBody {383 // If omitted or set to `true`, this response signals to the client that all384 // threads have been resumed. The value `false` indicates that not all threads385 // were resumed.386 bool allThreadsContinued = true;387};388llvm::json::Value toJSON(const ContinueResponseBody &);389 390/// Arguments for `completions` request.391struct CompletionsArguments {392 /// Returns completions in the scope of this stack frame. If not specified,393 /// the completions are returned for the global scope.394 uint64_t frameId = LLDB_DAP_INVALID_FRAME_ID;395 396 /// One or more source lines. Typically this is the text users have typed into397 /// the debug console before they asked for completion.398 std::string text;399 400 /// The position within `text` for which to determine the completion401 /// proposals. It is measured in UTF-16 code units and the client capability402 /// `columnsStartAt1` determines whether it is 0- or 1-based.403 int64_t column = 0;404 405 /// A line for which to determine the completion proposals. If missing the406 /// first line of the text is assumed.407 int64_t line = 0;408};409bool fromJSON(const llvm::json::Value &, CompletionsArguments &,410 llvm::json::Path);411 412/// Response to `completions` request.413struct CompletionsResponseBody {414 /// The possible completions for a given caret position and text.415 std::vector<CompletionItem> targets;416};417llvm::json::Value toJSON(const CompletionsResponseBody &);418 419/// Arguments for `configurationDone` request.420using ConfigurationDoneArguments = EmptyArguments;421 422/// Response to `configurationDone` request. This is just an acknowledgement, so423/// no body field is required.424using ConfigurationDoneResponse = VoidResponse;425 426/// Arguments for `setVariable` request.427struct SetVariableArguments {428 /// The reference of the variable container. The `variablesReference` must429 /// have been obtained in the current suspended state. See 'Lifetime of Object430 /// References' in the Overview section for details.431 uint64_t variablesReference = UINT64_MAX;432 433 /// The name of the variable in the container.434 std::string name;435 436 /// The value of the variable.437 std::string value;438 439 /// Specifies details on how to format the response value.440 ValueFormat format;441};442bool fromJSON(const llvm::json::Value &, SetVariableArguments &,443 llvm::json::Path);444 445/// Response to `setVariable` request.446struct SetVariableResponseBody {447 /// The new value of the variable.448 std::string value;449 450 /// The type of the new value. Typically shown in the UI when hovering over451 /// the value.452 std::string type;453 454 /// If `variablesReference` is > 0, the new value is structured and its455 /// children can be retrieved by passing `variablesReference` to the456 /// `variables` request as long as execution remains suspended. See 'Lifetime457 /// of Object References' in the Overview section for details.458 ///459 /// If this property is included in the response, any `variablesReference`460 /// previously associated with the updated variable, and those of its461 /// children, are no longer valid.462 uint64_t variablesReference = 0;463 464 /// The number of named child variables.465 /// The client can use this information to present the variables in a paged466 /// UI and fetch them in chunks.467 /// The value should be less than or equal to 2147483647 (2^31-1).468 uint32_t namedVariables = 0;469 470 /// The number of indexed child variables.471 /// The client can use this information to present the variables in a paged472 /// UI and fetch them in chunks.473 /// The value should be less than or equal to 2147483647 (2^31-1).474 uint32_t indexedVariables = 0;475 476 /// A memory reference to a location appropriate for this result.477 /// For pointer type eval results, this is generally a reference to the478 /// memory address contained in the pointer.479 /// This attribute may be returned by a debug adapter if corresponding480 /// capability `supportsMemoryReferences` is true.481 lldb::addr_t memoryReference = LLDB_INVALID_ADDRESS;482 483 /// A reference that allows the client to request the location where the new484 /// value is declared. For example, if the new value is function pointer, the485 /// adapter may be able to look up the function's location. This should be486 /// present only if the adapter is likely to be able to resolve the location.487 ///488 /// This reference shares the same lifetime as the `variablesReference`. See489 /// 'Lifetime of Object References' in the Overview section for details.490 uint64_t valueLocationReference = 0;491};492llvm::json::Value toJSON(const SetVariableResponseBody &);493 494struct ScopesArguments {495 /// Retrieve the scopes for the stack frame identified by `frameId`. The496 /// `frameId` must have been obtained in the current suspended state. See497 /// 'Lifetime of Object References' in the Overview section for details.498 uint64_t frameId = LLDB_DAP_INVALID_FRAME_ID;499};500bool fromJSON(const llvm::json::Value &, ScopesArguments &, llvm::json::Path);501 502struct ScopesResponseBody {503 std::vector<Scope> scopes;504};505llvm::json::Value toJSON(const ScopesResponseBody &);506 507/// Arguments for `source` request.508struct SourceArguments {509 /// Specifies the source content to load. Either `source.path` or510 /// `source.sourceReference` must be specified.511 std::optional<Source> source;512 513 /// The reference to the source. This is the same as `source.sourceReference`.514 /// This is provided for backward compatibility since old clients do not515 /// understand the `source` attribute.516 int64_t sourceReference = LLDB_DAP_INVALID_SRC_REF;517};518bool fromJSON(const llvm::json::Value &, SourceArguments &, llvm::json::Path);519 520/// Response to `source` request.521struct SourceResponseBody {522 /// Content of the source reference.523 std::string content;524 525 /// Content type (MIME type) of the source.526 std::optional<std::string> mimeType;527};528llvm::json::Value toJSON(const SourceResponseBody &);529 530/// Arguments for the `threads` request, no arguments.531using ThreadsArguments = EmptyArguments;532 533/// Response to `threads` request.534struct ThreadsResponseBody {535 /// All threads.536 std::vector<Thread> threads;537};538llvm::json::Value toJSON(const ThreadsResponseBody &);539 540/// Arguments for `next` request.541struct NextArguments {542 /// Specifies the thread for which to resume execution for one step (of the543 /// given granularity).544 lldb::tid_t threadId = LLDB_INVALID_THREAD_ID;545 546 /// If this flag is true, all other suspended threads are not resumed.547 bool singleThread = false;548 549 /// Stepping granularity. If no granularity is specified, a granularity of550 /// `statement` is assumed.551 SteppingGranularity granularity = eSteppingGranularityStatement;552};553bool fromJSON(const llvm::json::Value &, NextArguments &, llvm::json::Path);554 555/// Response to `next` request. This is just an acknowledgement, so no556/// body field is required.557using NextResponse = VoidResponse;558 559/// Arguments for `stepIn` request.560struct StepInArguments {561 /// Specifies the thread for which to resume execution for one step-into (of562 /// the given granularity).563 lldb::tid_t threadId = LLDB_INVALID_THREAD_ID;564 565 /// If this flag is true, all other suspended threads are not resumed.566 bool singleThread = false;567 568 /// Id of the target to step into.569 std::optional<uint64_t> targetId;570 571 /// Stepping granularity. If no granularity is specified, a granularity of572 /// `statement` is assumed.573 SteppingGranularity granularity = eSteppingGranularityStatement;574};575bool fromJSON(const llvm::json::Value &, StepInArguments &, llvm::json::Path);576 577/// Response to `stepIn` request. This is just an acknowledgement, so no578/// body field is required.579using StepInResponse = VoidResponse;580 581/// Arguments for `stepInTargets` request.582struct StepInTargetsArguments {583 /// The stack frame for which to retrieve the possible step-in targets.584 uint64_t frameId = LLDB_DAP_INVALID_FRAME_ID;585};586bool fromJSON(const llvm::json::Value &, StepInTargetsArguments &,587 llvm::json::Path);588 589/// Response to `stepInTargets` request.590struct StepInTargetsResponseBody {591 /// The possible step-in targets of the specified source location.592 std::vector<StepInTarget> targets;593};594llvm::json::Value toJSON(const StepInTargetsResponseBody &);595 596/// Arguments for `stepOut` request.597struct StepOutArguments {598 /// Specifies the thread for which to resume execution for one step-out (of599 /// the given granularity).600 lldb::tid_t threadId = LLDB_INVALID_THREAD_ID;601 602 /// If this flag is true, all other suspended threads are not resumed.603 std::optional<bool> singleThread;604 605 /// Stepping granularity. If no granularity is specified, a granularity of606 /// `statement` is assumed.607 SteppingGranularity granularity = eSteppingGranularityStatement;608};609bool fromJSON(const llvm::json::Value &, StepOutArguments &, llvm::json::Path);610 611/// Response to `stepOut` request. This is just an acknowledgement, so no612/// body field is required.613using StepOutResponse = VoidResponse;614 615/// Arguments for `breakpointLocations` request.616struct BreakpointLocationsArguments {617 /// The source location of the breakpoints; either `source.path` or618 /// `source.sourceReference` must be specified.619 Source source;620 621 /// Start line of range to search possible breakpoint locations in. If only622 /// the line is specified, the request returns all possible locations in that623 /// line.624 uint32_t line;625 626 /// Start position within `line` to search possible breakpoint locations in.627 /// It is measured in UTF-16 code units and the client capability628 /// `columnsStartAt1` determines whether it is 0- or 1-based. If no column is629 /// given, the first position in the start line is assumed.630 std::optional<uint32_t> column;631 632 /// End line of range to search possible breakpoint locations in. If no end633 /// line is given, then the end line is assumed to be the start line.634 std::optional<uint32_t> endLine;635 636 /// End position within `endLine` to search possible breakpoint locations in.637 /// It is measured in UTF-16 code units and the client capability638 /// `columnsStartAt1` determines whether it is 0- or 1-based. If no end column639 /// is given, the last position in the end line is assumed.640 std::optional<uint32_t> endColumn;641};642bool fromJSON(const llvm::json::Value &, BreakpointLocationsArguments &,643 llvm::json::Path);644 645/// Response to `breakpointLocations` request.646struct BreakpointLocationsResponseBody {647 /// Content of the source reference.648 std::vector<BreakpointLocation> breakpoints;649};650llvm::json::Value toJSON(const BreakpointLocationsResponseBody &);651 652/// Arguments for `setBreakpoints` request.653struct SetBreakpointsArguments {654 /// The source location of the breakpoints; either `source.path` or655 /// `source.sourceReference` must be specified.656 Source source;657 658 /// The code locations of the breakpoints.659 std::optional<std::vector<SourceBreakpoint>> breakpoints;660 661 /// Deprecated: The code locations of the breakpoints.662 std::optional<std::vector<uint32_t>> lines;663 664 /// A value of true indicates that the underlying source has been modified665 /// which results in new breakpoint locations.666 std::optional<bool> sourceModified;667};668bool fromJSON(const llvm::json::Value &, SetBreakpointsArguments &,669 llvm::json::Path);670 671/// Response to `setBreakpoints` request.672/// Returned is information about each breakpoint created by this request.673/// This includes the actual code location and whether the breakpoint could be674/// verified. The breakpoints returned are in the same order as the elements of675/// the breakpoints (or the deprecated lines) array in the arguments.676struct SetBreakpointsResponseBody {677 /// Information about the breakpoints.678 /// The array elements are in the same order as the elements of the679 /// `breakpoints` (or the deprecated `lines`) array in the arguments.680 std::vector<Breakpoint> breakpoints;681};682llvm::json::Value toJSON(const SetBreakpointsResponseBody &);683 684/// Arguments for `setFunctionBreakpoints` request.685struct SetFunctionBreakpointsArguments {686 /// The function names of the breakpoints.687 std::vector<FunctionBreakpoint> breakpoints;688};689bool fromJSON(const llvm::json::Value &, SetFunctionBreakpointsArguments &,690 llvm::json::Path);691 692/// Response to `setFunctionBreakpoints` request.693/// Returned is information about each breakpoint created by this request.694struct SetFunctionBreakpointsResponseBody {695 /// Information about the breakpoints. The array elements correspond to the696 /// elements of the `breakpoints` array.697 std::vector<Breakpoint> breakpoints;698};699llvm::json::Value toJSON(const SetFunctionBreakpointsResponseBody &);700 701/// Arguments for `setInstructionBreakpoints` request.702struct SetInstructionBreakpointsArguments {703 /// The instruction references of the breakpoints.704 std::vector<InstructionBreakpoint> breakpoints;705};706bool fromJSON(const llvm::json::Value &, SetInstructionBreakpointsArguments &,707 llvm::json::Path);708 709/// Response to `setInstructionBreakpoints` request.710struct SetInstructionBreakpointsResponseBody {711 /// Information about the breakpoints. The array elements correspond to the712 /// elements of the `breakpoints` array.713 std::vector<Breakpoint> breakpoints;714};715llvm::json::Value toJSON(const SetInstructionBreakpointsResponseBody &);716 717/// Arguments for `dataBreakpointInfo` request.718struct DataBreakpointInfoArguments {719 /// Reference to the variable container if the data breakpoint is requested720 /// for a child of the container. The `variablesReference` must have been721 /// obtained in the current suspended state.See 'Lifetime of Object722 /// References' in the Overview section for details.723 std::optional<int64_t> variablesReference;724 725 /// The name of the variable's child to obtain data breakpoint information726 /// for. If `variablesReference` isn't specified, this can be an expression,727 /// or an address if `asAddress` is also true.728 std::string name;729 730 /// When `name` is an expression, evaluate it in the scope of this stack731 /// frame. If not specified, the expression is evaluated in the global scope.732 /// When `asAddress` is true, the `frameId` is ignored.733 uint64_t frameId = LLDB_DAP_INVALID_FRAME_ID;734 735 /// If specified, a debug adapter should return information for the range of736 /// memory extending `bytes` number of bytes from the address or variable737 /// specified by `name`. Breakpoints set using the resulting data ID should738 /// pause on data access anywhere within that range.739 /// Clients may set this property only if the `supportsDataBreakpointBytes`740 /// capability is true.741 std::optional<int64_t> bytes;742 743 /// If `true`, the `name` is a memory address and the debugger should744 /// interpret it as a decimal value, or hex value if it is prefixed with `0x`.745 /// Clients may set this property only if the `supportsDataBreakpointBytes`746 /// capability is true.747 std::optional<bool> asAddress;748 749 /// The mode of the desired breakpoint. If defined, this must be one of the750 /// `breakpointModes` the debug adapter advertised in its `Capabilities`.751 std::optional<std::string> mode;752};753bool fromJSON(const llvm::json::Value &, DataBreakpointInfoArguments &,754 llvm::json::Path);755 756/// Response to `dataBreakpointInfo` request.757struct DataBreakpointInfoResponseBody {758 /// An identifier for the data on which a data breakpoint can be registered759 /// with the `setDataBreakpoints` request or null if no data breakpoint is760 /// available. If a `variablesReference` or `frameId` is passed, the `dataId`761 /// is valid in the current suspended state, otherwise it's valid762 /// indefinitely. See 'Lifetime of Object References' in the Overview section763 /// for details. Breakpoints set using the `dataId` in the764 /// `setDataBreakpoints` request may outlive the lifetime of the associated765 /// `dataId`.766 std::optional<std::string> dataId;767 768 /// UI string that describes on what data the breakpoint is set on or why a769 /// data breakpoint is not available.770 std::string description;771 772 /// Attribute lists the available access types for a potential data773 /// breakpoint. A UI client could surface this information.774 std::optional<std::vector<DataBreakpointAccessType>> accessTypes;775 776 /// Attribute indicates that a potential data breakpoint could be persisted777 /// across sessions.778 std::optional<bool> canPersist;779};780llvm::json::Value toJSON(const DataBreakpointInfoResponseBody &);781 782/// Arguments for `setDataBreakpoints` request.783struct SetDataBreakpointsArguments {784 /// The contents of this array replaces all existing data breakpoints. An785 /// empty array clears all data breakpoints.786 std::vector<DataBreakpoint> breakpoints;787};788bool fromJSON(const llvm::json::Value &, SetDataBreakpointsArguments &,789 llvm::json::Path);790 791/// Response to `setDataBreakpoints` request.792struct SetDataBreakpointsResponseBody {793 /// Information about the data breakpoints. The array elements correspond to794 /// the elements of the input argument `breakpoints` array.795 std::vector<Breakpoint> breakpoints;796};797llvm::json::Value toJSON(const SetDataBreakpointsResponseBody &);798 799/// Arguments for `setExceptionBreakpoints` request.800struct SetExceptionBreakpointsArguments {801 /// Set of exception filters specified by their ID. The set of all possible802 /// exception filters is defined by the `exceptionBreakpointFilters`803 /// capability. The `filter` and `filterOptions` sets are additive.804 std::vector<std::string> filters;805 806 /// Set of exception filters and their options. The set of all possible807 /// exception filters is defined by the `exceptionBreakpointFilters`808 /// capability. This attribute is only honored by a debug adapter if the809 /// corresponding capability `supportsExceptionFilterOptions` is true. The810 /// `filter` and `filterOptions` sets are additive.811 std::vector<ExceptionFilterOptions> filterOptions;812 813 // unsupported keys: exceptionOptions814};815bool fromJSON(const llvm::json::Value &, SetExceptionBreakpointsArguments &,816 llvm::json::Path);817 818/// Response to `setExceptionBreakpoints` request.819///820/// The response contains an array of `Breakpoint` objects with information821/// about each exception breakpoint or filter. The `Breakpoint` objects are in822/// the same order as the elements of the `filters`, `filterOptions`,823/// `exceptionOptions` arrays given as arguments. If both `filters` and824/// `filterOptions` are given, the returned array must start with `filters`825/// information first, followed by `filterOptions` information.826///827/// The `verified` property of a `Breakpoint` object signals whether the828/// exception breakpoint or filter could be successfully created and whether the829/// condition is valid. In case of an error the `message` property explains the830/// problem. The `id` property can be used to introduce a unique ID for the831/// exception breakpoint or filter so that it can be updated subsequently by832/// sending breakpoint events.833///834/// For backward compatibility both the `breakpoints` array and the enclosing835/// `body` are optional. If these elements are missing a client is not able to836/// show problems for individual exception breakpoints or filters.837struct SetExceptionBreakpointsResponseBody {838 /// Information about the exception breakpoints or filters.839 ///840 /// The breakpoints returned are in the same order as the elements of the841 /// `filters`, `filterOptions`, `exceptionOptions` arrays in the arguments. If842 /// both `filters` and `filterOptions` are given, the returned array must843 /// start with `filters` information first, followed by `filterOptions`844 /// information.845 std::vector<Breakpoint> breakpoints;846};847llvm::json::Value toJSON(const SetExceptionBreakpointsResponseBody &);848 849/// Arguments to `disassemble` request.850struct DisassembleArguments {851 /// Memory reference to the base location containing the instructions to852 /// disassemble.853 lldb::addr_t memoryReference = LLDB_INVALID_ADDRESS;854 855 /// Offset (in bytes) to be applied to the reference location before856 /// disassembling. Can be negative.857 int64_t offset = 0;858 859 /// Offset (in instructions) to be applied after the byte offset (if any)860 /// before disassembling. Can be negative.861 int64_t instructionOffset = 0;862 863 /// Number of instructions to disassemble starting at the specified location864 /// and offset.865 /// An adapter must return exactly this number of instructions - any866 /// unavailable instructions should be replaced with an implementation-defined867 /// 'invalid instruction' value.868 uint32_t instructionCount = 0;869 870 /// If true, the adapter should attempt to resolve memory addresses and other871 /// values to symbolic names.872 bool resolveSymbols = false;873};874bool fromJSON(const llvm::json::Value &, DisassembleArguments &,875 llvm::json::Path);876llvm::json::Value toJSON(const DisassembleArguments &);877 878/// Response to `disassemble` request.879struct DisassembleResponseBody {880 /// The list of disassembled instructions.881 std::vector<DisassembledInstruction> instructions;882};883bool fromJSON(const llvm::json::Value &, DisassembleResponseBody &,884 llvm::json::Path);885llvm::json::Value toJSON(const DisassembleResponseBody &);886 887/// Arguments for `readMemory` request.888struct ReadMemoryArguments {889 /// Memory reference to the base location from which data should be read.890 lldb::addr_t memoryReference = LLDB_INVALID_ADDRESS;891 892 /// Offset (in bytes) to be applied to the reference location before reading893 /// data. Can be negative.894 int64_t offset = 0;895 896 /// Number of bytes to read at the specified location and offset.897 uint64_t count = 0;898};899bool fromJSON(const llvm::json::Value &, ReadMemoryArguments &,900 llvm::json::Path);901 902/// Response to `readMemory` request.903struct ReadMemoryResponseBody {904 /// The address of the first byte of data returned.905 /// Treated as a hex value if prefixed with `0x`, or as a decimal value906 /// otherwise.907 lldb::addr_t address = LLDB_INVALID_ADDRESS;908 909 /// The number of unreadable bytes encountered after the last successfully910 /// read byte.911 /// This can be used to determine the number of bytes that should be skipped912 /// before a subsequent `readMemory` request succeeds.913 uint64_t unreadableBytes = 0;914 915 /// The bytes read from memory, encoded using base64. If the decoded length916 /// of `data` is less than the requested `count` in the original `readMemory`917 /// request, and `unreadableBytes` is zero or omitted, then the client should918 /// assume it's reached the end of readable memory.919 std::vector<std::byte> data;920};921llvm::json::Value toJSON(const ReadMemoryResponseBody &);922 923/// Arguments for `modules` request.924struct ModulesArguments {925 /// The index of the first module to return; if omitted modules start at 0.926 uint32_t startModule = 0;927 928 /// The number of modules to return. If `moduleCount` is not specified or 0,929 /// all modules are returned.930 uint32_t moduleCount = 0;931};932bool fromJSON(const llvm::json::Value &, ModulesArguments &, llvm::json::Path);933 934/// Response to `modules` request.935struct ModulesResponseBody {936 /// All modules or range of modules.937 std::vector<Module> modules;938 939 /// The total number of modules available.940 uint32_t totalModules = 0;941};942llvm::json::Value toJSON(const ModulesResponseBody &);943 944/// Arguments for `variables` request.945struct VariablesArguments {946 /// The variable for which to retrieve its children. The `variablesReference`947 /// must have been obtained in the current suspended state. See 'Lifetime of948 /// Object References' in the Overview section for details.949 uint64_t variablesReference;950 951 enum VariablesFilter : unsigned {952 eVariablesFilterBoth = 0,953 eVariablesFilterIndexed = 1 << 0,954 eVariablesFilterNamed = 1 << 1,955 };956 957 /// Filter to limit the child variables to either named or indexed. If958 /// omitted, both types are fetched.959 VariablesFilter filter = eVariablesFilterBoth;960 961 /// The index of the first variable to return; if omitted children start at 0.962 ///963 /// The attribute is only honored by a debug adapter if the corresponding964 /// capability `supportsVariablePaging` is true.965 uint64_t start = 0;966 967 /// The number of variables to return. If count is missing or 0, all variables968 /// are returned.969 ///970 /// The attribute is only honored by a debug adapter if the corresponding971 /// capability `supportsVariablePaging` is true.972 uint64_t count = 0;973 974 /// Specifies details on how to format the Variable values.975 ///976 /// The attribute is only honored by a debug adapter if the corresponding977 /// capability `supportsValueFormattingOptions` is true.978 std::optional<ValueFormat> format;979};980bool fromJSON(const llvm::json::Value &Param,981 VariablesArguments::VariablesFilter &VA, llvm::json::Path Path);982bool fromJSON(const llvm::json::Value &, VariablesArguments &,983 llvm::json::Path);984 985/// Response to `variables` request.986struct VariablesResponseBody {987 /// All (or a range) of variables for the given variable reference.988 std::vector<Variable> variables;989};990llvm::json::Value toJSON(const VariablesResponseBody &);991 992/// Arguments for `writeMemory` request.993struct WriteMemoryArguments {994 /// Memory reference to the base location to which data should be written.995 lldb::addr_t memoryReference = LLDB_INVALID_ADDRESS;996 997 /// Offset (in bytes) to be applied to the reference location before writing998 /// data. Can be negative.999 int64_t offset = 0;1000 1001 /// Property to control partial writes. If true, the debug adapter should1002 /// attempt to write memory even if the entire memory region is not writable.1003 /// In such a case the debug adapter should stop after hitting the first byte1004 /// of memory that cannot be written and return the number of bytes written in1005 /// the response via the `offset` and `bytesWritten` properties.1006 /// If false or missing, a debug adapter should attempt to verify the region1007 /// is writable before writing, and fail the response if it is not.1008 bool allowPartial = false;1009 1010 /// Bytes to write, encoded using base64.1011 std::string data;1012};1013bool fromJSON(const llvm::json::Value &, WriteMemoryArguments &,1014 llvm::json::Path);1015 1016/// Response to writeMemory request.1017struct WriteMemoryResponseBody {1018 /// Property that should be returned when `allowPartial` is true to indicate1019 /// the number of bytes starting from address that were successfully written.1020 uint64_t bytesWritten = 0;1021};1022llvm::json::Value toJSON(const WriteMemoryResponseBody &);1023 1024struct ModuleSymbolsArguments {1025 /// The module UUID for which to retrieve symbols.1026 std::string moduleId;1027 1028 /// The module path.1029 std::string moduleName;1030 1031 /// The index of the first symbol to return; if omitted, start at the1032 /// beginning.1033 std::optional<uint32_t> startIndex;1034 1035 /// The number of symbols to return; if omitted, all symbols are returned.1036 std::optional<uint32_t> count;1037};1038bool fromJSON(const llvm::json::Value &, ModuleSymbolsArguments &,1039 llvm::json::Path);1040 1041/// Response to `getModuleSymbols` request.1042struct ModuleSymbolsResponseBody {1043 /// The symbols for the specified module.1044 std::vector<Symbol> symbols;1045};1046llvm::json::Value toJSON(const ModuleSymbolsResponseBody &);1047 1048struct ExceptionInfoArguments {1049 /// Thread for which exception information should be retrieved.1050 lldb::tid_t threadId = LLDB_INVALID_THREAD_ID;1051};1052bool fromJSON(const llvm::json::Value &, ExceptionInfoArguments &,1053 llvm::json::Path);1054 1055struct ExceptionInfoResponseBody {1056 /// ID of the exception that was thrown.1057 std::string exceptionId;1058 1059 /// Descriptive text for the exception.1060 std::string description;1061 1062 /// Mode that caused the exception notification to be raised.1063 ExceptionBreakMode breakMode = eExceptionBreakModeNever;1064 1065 /// Detailed information about the exception.1066 std::optional<ExceptionDetails> details;1067};1068llvm::json::Value toJSON(const ExceptionInfoResponseBody &);1069 1070/// The context in which the evaluate request is used.1071enum EvaluateContext : unsigned {1072 /// An unspecified or unknown evaluate context.1073 eEvaluateContextUnknown = 0,1074 /// 'watch': evaluate is called from a watch view context.1075 eEvaluateContextWatch = 1,1076 /// 'repl': evaluate is called from a REPL context.1077 eEvaluateContextRepl = 2,1078 /// 'hover': evaluate is called to generate the debug hover contents.1079 /// This value should only be used if the corresponding capability1080 /// `supportsEvaluateForHovers` is true.1081 eEvaluateContextHover = 3,1082 /// 'clipboard': evaluate is called to generate clipboard contents.1083 /// This value should only be used if the corresponding capability1084 /// `supportsClipboardContext` is true.1085 eEvaluateContextClipboard = 4,1086 /// 'variables': evaluate is called from a variables view context.1087 eEvaluateContextVariables = 5,1088};1089 1090/// Arguments for `evaluate` request.1091struct EvaluateArguments {1092 /// The expression to evaluate.1093 std::string expression;1094 1095 /// Evaluate the expression in the scope of this stack frame. If not1096 /// specified, the expression is evaluated in the global scope.1097 uint64_t frameId = LLDB_DAP_INVALID_FRAME_ID;1098 1099 /// The contextual line where the expression should be evaluated. In the1100 /// 'hover' context, this should be set to the start of the expression being1101 /// hovered.1102 uint32_t line = LLDB_INVALID_LINE_NUMBER;1103 1104 /// The contextual column where the expression should be evaluated. This may1105 /// be provided if `line` is also provided.1106 ///1107 /// It is measured in UTF-16 code units and the client capability1108 /// `columnsStartAt1` determines whether it is 0- or 1-based.1109 uint32_t column = LLDB_INVALID_COLUMN_NUMBER;1110 1111 /// The contextual source in which the `line` is found. This must be provided1112 /// if `line` is provided.1113 std::optional<Source> source;1114 1115 /// The context in which the evaluate request is used.1116 /// Values:1117 /// 'watch': evaluate is called from a watch view context.1118 /// 'repl': evaluate is called from a REPL context.1119 /// 'hover': evaluate is called to generate the debug hover contents.1120 /// This value should only be used if the corresponding capability1121 /// `supportsEvaluateForHovers` is true.1122 /// 'clipboard': evaluate is called to generate clipboard contents.1123 /// This value should only be used if the corresponding capability1124 /// `supportsClipboardContext` is true.1125 /// 'variables': evaluate is called from a variables view context.1126 /// etc.1127 EvaluateContext context = eEvaluateContextUnknown;1128 1129 /// Specifies details on how to format the result.1130 /// The attribute is only honored by a debug adapter if the corresponding1131 /// capability `supportsValueFormattingOptions` is true.1132 std::optional<ValueFormat> format;1133};1134bool fromJSON(const llvm::json::Value &, EvaluateArguments &, llvm::json::Path);1135 1136/// Response to 'evaluate' request.1137struct EvaluateResponseBody {1138 /// The result of the evaluate request.1139 std::string result;1140 1141 /// The type of the evaluate result.1142 /// This attribute should only be returned by a debug adapter if the1143 /// corresponding capability `supportsVariableType` is true.1144 std::string type;1145 1146 /// Properties of an evaluate result that can be used to determine how to1147 /// render the result in the UI.1148 std::optional<VariablePresentationHint> presentationHint;1149 1150 /// If `variablesReference` is > 0, the evaluate result is structured and its1151 /// children can be retrieved by passing `variablesReference` to the1152 /// `variables` request as long as execution remains suspended. See 'Lifetime1153 /// of Object References' in the Overview section for details.1154 int64_t variablesReference = 0;1155 1156 /// The number of named child variables.1157 /// The client can use this information to present the variables in a paged1158 /// UI and fetch them in chunks.1159 /// The value should be less than or equal to 2147483647 (2^31-1).1160 uint32_t namedVariables = 0;1161 1162 /// The number of indexed child variables.1163 /// The client can use this information to present the variables in a paged1164 /// UI and fetch them in chunks.1165 /// The value should be less than or equal to 2147483647 (2^31-1).1166 uint32_t indexedVariables = 0;1167 1168 /// A memory reference to a location appropriate for this result.1169 /// For pointer type eval results, this is generally a reference to the1170 /// memory address contained in the pointer.1171 /// This attribute may be returned by a debug adapter if corresponding1172 /// capability `supportsMemoryReferences` is true.1173 std::string memoryReference;1174 1175 /// A reference that allows the client to request the location where the1176 /// returned value is declared. For example, if a function pointer is1177 /// returned, the adapter may be able to look up the function's location.1178 /// This should be present only if the adapter is likely to be able to1179 /// resolve the location.1180 ///1181 /// This reference shares the same lifetime as the `variablesReference`. See1182 /// 'Lifetime of Object References' in the Overview section for details.1183 uint64_t valueLocationReference = LLDB_DAP_INVALID_VALUE_LOC;1184};1185llvm::json::Value toJSON(const EvaluateResponseBody &);1186 1187} // namespace lldb_dap::protocol1188 1189#endif1190