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-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This file contains POD structs based on the DAP specification at
10// https://microsoft.github.io/debug-adapter-protocol/specification
11//
12// This is not meant to be a complete implementation, new interfaces are added
13// when they're needed.
14//
15// Each struct has a toJSON and fromJSON function, that converts between
16// the struct and a JSON representation. (See JSON.h)
17//
18//===----------------------------------------------------------------------===//
19
20#ifndef LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_REQUESTS_H
21#define LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_REQUESTS_H
22
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 request
41 /// 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 no
47 /// 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 body
55/// 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 a
61 /// restart sequence.
62 std::optional<bool> restart;
63
64 /// Indicates whether the debuggee should be terminated when the debugger is
65 /// disconnected. If unspecified, the debug adapter is free to do whatever it
66 /// thinks is best. The attribute is only honored by a debug adapter if the
67 /// corresponding capability `supportTerminateDebuggee` is true.
68 std::optional<bool> terminateDebuggee;
69
70 /// Indicates whether the debuggee should stay suspended when the debugger is
71 /// disconnected. If unspecified, the debuggee should resume execution. The
72 /// attribute is only honored by a debug adapter if the corresponding
73 /// 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 no
80/// 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 the
93 /// `runInTerminal` request.
94 eClientFeatureArgsCanBeInterpretedByShell,
95 eClientFeatureStartDebuggingRequest,
96 /// The client will interpret ANSI escape sequences in the display of
97 /// `OutputEvent.output` and `Variable.value` fields when
98 /// `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 Extensions
133 /// @{
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 debug
152 /// information in your executable contains relative paths, this option can be
153 /// used so that `lldb-dap` can find source files and object files that have
154 /// relative paths.
155 std::string debuggerRoot;
156
157 /// Enable auto generated summaries for variables when no summaries exist for
158 /// a given type. This feature can cause performance delays in large projects
159 /// when viewing variables.
160 bool enableAutoVariableSummaries = false;
161
162 /// If a variable is displayed using a synthetic children, also display the
163 /// actual contents of the variable at the end under a [raw] entry. This is
164 /// useful when creating synthetic child plug-ins as it lets you see the
165 /// 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` or
175 /// attach.
176 std::chrono::seconds timeout = std::chrono::seconds(30);
177
178 /// The escape prefix to use for executing regular LLDB commands in the Debug
179 /// Console, instead of printing variables. Defaults to a backtick. If it's an
180 /// empty string, then all expression in the Debug Console are treated as
181 /// regular LLDB commands.
182 std::string commandEscapePrefix = "`";
183
184 /// If non-empty, stack frames will have descriptions generated based on the
185 /// provided format. See https://lldb.llvm.org/use/formatting.html for an
186 /// explanation on format strings for frames. If the format string contains
187 /// errors, an error message will be displayed on the Debug Console and the
188 /// default frame names will be used. This might come with a performance cost
189 /// because debug information might need to be processed to generate the
190 /// 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 when
197 /// 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 a
201 /// two element array containing a source and destination pathname. Overrides
202 /// sourcePath.
203 std::vector<std::pair<std::string, std::string>> sourceMap;
204
205 /// LLDB commands executed upon debugger startup prior to creating the LLDB
206 /// target.
207 std::vector<std::string> preInitCommands;
208
209 /// LLDB commands executed upon debugger startup prior to creating the LLDB
210 /// target.
211 std::vector<std::string> initCommands;
212
213 /// LLDB commands executed just before launching/attaching, after the LLDB
214 /// target has been created.
215 std::vector<std::string> preRunCommands;
216
217 /// LLDB commands executed just after launching/attaching, after the LLDB
218 /// 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 be
233 /// 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 from
237 /// the binary.
238 std::string targetTriple;
239
240 /// Specify name of the platform to use for this target, creating the platform
241 /// if necessary.
242 std::string platformName;
243};
244
245enum Console : unsigned {
246 eConsoleInternal,
247 eConsoleIntegratedTerminal,
248 eConsoleExternalTerminal
249};
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 enabling
257 /// 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 program
277 /// being launched.
278 std::vector<std::string> args;
279
280 /// Environment variables to set when launching the program. The format of
281 /// each environment variable string is "VAR=VALUE" for environment variables
282 /// 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 the
286 /// debuggee if it loses connection with lldb.
287 bool detachOnError = false;
288
289 /// Disable ASLR (Address Space Layout Randomization) when launching the
290 /// 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, integrated
300 /// terminal or external terminal.
301 Console console = eConsoleInternal;
302
303 /// @}
304};
305bool fromJSON(const llvm::json::Value &, LaunchRequestArguments &,
306 llvm::json::Path);
307
308/// Response to `launch` request. This is just an acknowledgement, so no body
309/// field is required.
310using LaunchResponse = VoidResponse;
311
312#define LLDB_DAP_INVALID_PORT -1
313
314/// lldb-dap specific attach arguments.
315struct AttachRequestArguments {
316 /// Common lldb-dap configuration values for launching/attaching operations.
317 Configuration configuration;
318
319 /// Attach specific operations.
320 ///
321 /// See package.json debuggers > configurationAttributes > attach >
322 /// properties.
323 /// @{
324
325 /// Custom commands that are executed instead of attaching to a process ID or
326 /// to a process by name. These commands may optionally create a new target
327 /// and must perform an attach. A valid process must exist after these
328 /// commands complete or the `"attach"` will fail.
329 std::vector<std::string> attachCommands;
330
331 /// System process ID to attach to.
332 lldb::pid_t pid = LLDB_INVALID_PROCESS_ID;
333
334 /// Wait for the process to launch.
335 bool waitFor = false;
336
337 /// TCP/IP port to attach to a remote system. Specifying both pid and port is
338 /// an error.
339 int32_t gdbRemotePort = LLDB_DAP_INVALID_PORT;
340
341 /// The hostname to connect to a remote system. The default hostname being
342 /// used `localhost`.
343 std::string gdbRemoteHostname = "localhost";
344
345 /// Path to the core file to debug.
346 std::string coreFile;
347
348 /// @}
349};
350bool fromJSON(const llvm::json::Value &, AttachRequestArguments &,
351 llvm::json::Path);
352
353/// Response to `attach` request. This is just an acknowledgement, so no body
354/// field is required.
355using AttachResponse = VoidResponse;
356
357/// Arguments for `continue` request.
358struct ContinueArguments {
359 /// Specifies the active thread. If the debug adapter supports single thread
360 /// execution (see `supportsSingleThreadExecutionRequests`) and the argument
361 /// `singleThread` is true, only the thread with this ID is resumed.
362 lldb::tid_t threadId = LLDB_INVALID_THREAD_ID;
363
364 /// If this flag is true, execution is resumed only for the thread with given
365 /// `threadId`.
366 bool singleThread = false;
367};
368bool fromJSON(const llvm::json::Value &, ContinueArguments &, llvm::json::Path);
369
370/// Response to `continue` request.
371struct ContinueResponseBody {
372 // If omitted or set to `true`, this response signals to the client that all
373 // threads have been resumed. The value `false` indicates that not all threads
374 // were resumed.
375 bool allThreadsContinued = true;
376};
377llvm::json::Value toJSON(const ContinueResponseBody &);
378
379/// Arguments for `configurationDone` request.
380using ConfigurationDoneArguments = EmptyArguments;
381
382/// Response to `configurationDone` request. This is just an acknowledgement, so
383/// no body field is required.
384using ConfigurationDoneResponse = VoidResponse;
385
386/// Arguments for `setVariable` request.
387struct SetVariableArguments {
388 /// The reference of the variable container. The `variablesReference` must
389 /// have been obtained in the current suspended state. See 'Lifetime of Object
390 /// References' in the Overview section for details.
391 uint64_t variablesReference = UINT64_MAX;
392
393 /// The name of the variable in the container.
394 std::string name;
395
396 /// The value of the variable.
397 std::string value;
398
399 /// Specifies details on how to format the response value.
400 ValueFormat format;
401};
402bool fromJSON(const llvm::json::Value &, SetVariableArguments &,
403 llvm::json::Path);
404
405/// Response to `setVariable` request.
406struct SetVariableResponseBody {
407 /// The new value of the variable.
408 std::string value;
409
410 /// The type of the new value. Typically shown in the UI when hovering over
411 /// the value.
412 std::string type;
413
414 /// If `variablesReference` is > 0, the new value is structured and its
415 /// children can be retrieved by passing `variablesReference` to the
416 /// `variables` request as long as execution remains suspended. See 'Lifetime
417 /// of Object References' in the Overview section for details.
418 ///
419 /// If this property is included in the response, any `variablesReference`
420 /// previously associated with the updated variable, and those of its
421 /// children, are no longer valid.
422 uint64_t variablesReference = 0;
423
424 /// The number of named child variables.
425 /// The client can use this information to present the variables in a paged
426 /// UI and fetch them in chunks.
427 /// The value should be less than or equal to 2147483647 (2^31-1).
428 uint32_t namedVariables = 0;
429
430 /// The number of indexed child variables.
431 /// The client can use this information to present the variables in a paged
432 /// UI and fetch them in chunks.
433 /// The value should be less than or equal to 2147483647 (2^31-1).
434 uint32_t indexedVariables = 0;
435
436 /// A memory reference to a location appropriate for this result.
437 /// For pointer type eval results, this is generally a reference to the
438 /// memory address contained in the pointer.
439 /// This attribute may be returned by a debug adapter if corresponding
440 /// capability `supportsMemoryReferences` is true.
441 lldb::addr_t memoryReference = LLDB_INVALID_ADDRESS;
442
443 /// A reference that allows the client to request the location where the new
444 /// value is declared. For example, if the new value is function pointer, the
445 /// adapter may be able to look up the function's location. This should be
446 /// present only if the adapter is likely to be able to resolve the location.
447 ///
448 /// This reference shares the same lifetime as the `variablesReference`. See
449 /// 'Lifetime of Object References' in the Overview section for details.
450 uint64_t valueLocationReference = 0;
451};
452llvm::json::Value toJSON(const SetVariableResponseBody &);
453
454struct ScopesArguments {
455 /// Retrieve the scopes for the stack frame identified by `frameId`. The
456 /// `frameId` must have been obtained in the current suspended state. See
457 /// 'Lifetime of Object References' in the Overview section for details.
458 uint64_t frameId = LLDB_INVALID_FRAME_ID;
459};
460bool fromJSON(const llvm::json::Value &, ScopesArguments &, llvm::json::Path);
461
462struct ScopesResponseBody {
463 std::vector<Scope> scopes;
464};
465llvm::json::Value toJSON(const ScopesResponseBody &);
466
467/// Arguments for `source` request.
468struct SourceArguments {
469 /// Specifies the source content to load. Either `source.path` or
470 /// `source.sourceReference` must be specified.
471 std::optional<Source> source;
472
473 /// The reference to the source. This is the same as `source.sourceReference`.
474 /// This is provided for backward compatibility since old clients do not
475 /// understand the `source` attribute.
476 int64_t sourceReference = LLDB_DAP_INVALID_SRC_REF;
477};
478bool fromJSON(const llvm::json::Value &, SourceArguments &, llvm::json::Path);
479
480/// Response to `source` request.
481struct SourceResponseBody {
482 /// Content of the source reference.
483 std::string content;
484
485 /// Content type (MIME type) of the source.
486 std::optional<std::string> mimeType;
487};
488llvm::json::Value toJSON(const SourceResponseBody &);
489
490/// Arguments for the `threads` request, no arguments.
491using ThreadsArguments = EmptyArguments;
492
493/// Response to `threads` request.
494struct ThreadsResponseBody {
495 /// All threads.
496 std::vector<Thread> threads;
497};
498llvm::json::Value toJSON(const ThreadsResponseBody &);
499
500/// Arguments for `next` request.
501struct NextArguments {
502 /// Specifies the thread for which to resume execution for one step (of the
503 /// given granularity).
504 lldb::tid_t threadId = LLDB_INVALID_THREAD_ID;
505
506 /// If this flag is true, all other suspended threads are not resumed.
507 bool singleThread = false;
508
509 /// Stepping granularity. If no granularity is specified, a granularity of
510 /// `statement` is assumed.
511 SteppingGranularity granularity = eSteppingGranularityStatement;
512};
513bool fromJSON(const llvm::json::Value &, NextArguments &, llvm::json::Path);
514
515/// Response to `next` request. This is just an acknowledgement, so no
516/// body field is required.
517using NextResponse = VoidResponse;
518
519/// Arguments for `stepIn` request.
520struct StepInArguments {
521 /// Specifies the thread for which to resume execution for one step-into (of
522 /// the given granularity).
523 lldb::tid_t threadId = LLDB_INVALID_THREAD_ID;
524
525 /// If this flag is true, all other suspended threads are not resumed.
526 bool singleThread = false;
527
528 /// Id of the target to step into.
529 std::optional<uint64_t> targetId;
530
531 /// Stepping granularity. If no granularity is specified, a granularity of
532 /// `statement` is assumed.
533 SteppingGranularity granularity = eSteppingGranularityStatement;
534};
535bool fromJSON(const llvm::json::Value &, StepInArguments &, llvm::json::Path);
536
537/// Response to `stepIn` request. This is just an acknowledgement, so no
538/// body field is required.
539using StepInResponse = VoidResponse;
540
541/// Arguments for `stepInTargets` request.
542struct StepInTargetsArguments {
543 /// The stack frame for which to retrieve the possible step-in targets.
544 uint64_t frameId = LLDB_INVALID_FRAME_ID;
545};
546bool fromJSON(const llvm::json::Value &, StepInTargetsArguments &,
547 llvm::json::Path);
548
549/// Response to `stepInTargets` request.
550struct StepInTargetsResponseBody {
551 /// The possible step-in targets of the specified source location.
552 std::vector<StepInTarget> targets;
553};
554llvm::json::Value toJSON(const StepInTargetsResponseBody &);
555
556/// Arguments for `stepOut` request.
557struct StepOutArguments {
558 /// Specifies the thread for which to resume execution for one step-out (of
559 /// the given granularity).
560 lldb::tid_t threadId = LLDB_INVALID_THREAD_ID;
561
562 /// If this flag is true, all other suspended threads are not resumed.
563 std::optional<bool> singleThread;
564
565 /// Stepping granularity. If no granularity is specified, a granularity of
566 /// `statement` is assumed.
567 SteppingGranularity granularity = eSteppingGranularityStatement;
568};
569bool fromJSON(const llvm::json::Value &, StepOutArguments &, llvm::json::Path);
570
571/// Response to `stepOut` request. This is just an acknowledgement, so no
572/// body field is required.
573using StepOutResponse = VoidResponse;
574
575/// Arguments for `breakpointLocations` request.
576struct BreakpointLocationsArguments {
577 /// The source location of the breakpoints; either `source.path` or
578 /// `source.sourceReference` must be specified.
579 Source source;
580
581 /// Start line of range to search possible breakpoint locations in. If only
582 /// the line is specified, the request returns all possible locations in that
583 /// line.
584 uint32_t line;
585
586 /// Start position within `line` to search possible breakpoint locations in.
587 /// It is measured in UTF-16 code units and the client capability
588 /// `columnsStartAt1` determines whether it is 0- or 1-based. If no column is
589 /// given, the first position in the start line is assumed.
590 std::optional<uint32_t> column;
591
592 /// End line of range to search possible breakpoint locations in. If no end
593 /// line is given, then the end line is assumed to be the start line.
594 std::optional<uint32_t> endLine;
595
596 /// End position within `endLine` to search possible breakpoint locations in.
597 /// It is measured in UTF-16 code units and the client capability
598 /// `columnsStartAt1` determines whether it is 0- or 1-based. If no end column
599 /// is given, the last position in the end line is assumed.
600 std::optional<uint32_t> endColumn;
601};
602bool fromJSON(const llvm::json::Value &, BreakpointLocationsArguments &,
603 llvm::json::Path);
604
605/// Response to `breakpointLocations` request.
606struct BreakpointLocationsResponseBody {
607 /// Content of the source reference.
608 std::vector<BreakpointLocation> breakpoints;
609};
610llvm::json::Value toJSON(const BreakpointLocationsResponseBody &);
611
612/// Arguments for `setBreakpoints` request.
613struct SetBreakpointsArguments {
614 /// The source location of the breakpoints; either `source.path` or
615 /// `source.sourceReference` must be specified.
616 Source source;
617
618 /// The code locations of the breakpoints.
619 std::optional<std::vector<SourceBreakpoint>> breakpoints;
620
621 /// Deprecated: The code locations of the breakpoints.
622 std::optional<std::vector<uint32_t>> lines;
623
624 /// A value of true indicates that the underlying source has been modified
625 /// which results in new breakpoint locations.
626 std::optional<bool> sourceModified;
627};
628bool fromJSON(const llvm::json::Value &, SetBreakpointsArguments &,
629 llvm::json::Path);
630
631/// Response to `setBreakpoints` request.
632/// Returned is information about each breakpoint created by this request.
633/// This includes the actual code location and whether the breakpoint could be
634/// verified. The breakpoints returned are in the same order as the elements of
635/// the breakpoints (or the deprecated lines) array in the arguments.
636struct SetBreakpointsResponseBody {
637 /// Information about the breakpoints.
638 /// The array elements are in the same order as the elements of the
639 /// `breakpoints` (or the deprecated `lines`) array in the arguments.
640 std::vector<Breakpoint> breakpoints;
641};
642llvm::json::Value toJSON(const SetBreakpointsResponseBody &);
643
644/// Arguments for `setFunctionBreakpoints` request.
645struct SetFunctionBreakpointsArguments {
646 /// The function names of the breakpoints.
647 std::vector<FunctionBreakpoint> breakpoints;
648};
649bool fromJSON(const llvm::json::Value &, SetFunctionBreakpointsArguments &,
650 llvm::json::Path);
651
652/// Response to `setFunctionBreakpoints` request.
653/// Returned is information about each breakpoint created by this request.
654struct SetFunctionBreakpointsResponseBody {
655 /// Information about the breakpoints. The array elements correspond to the
656 /// elements of the `breakpoints` array.
657 std::vector<Breakpoint> breakpoints;
658};
659llvm::json::Value toJSON(const SetFunctionBreakpointsResponseBody &);
660
661/// Arguments for `setInstructionBreakpoints` request.
662struct SetInstructionBreakpointsArguments {
663 /// The instruction references of the breakpoints.
664 std::vector<InstructionBreakpoint> breakpoints;
665};
666bool fromJSON(const llvm::json::Value &, SetInstructionBreakpointsArguments &,
667 llvm::json::Path);
668
669/// Response to `setInstructionBreakpoints` request.
670struct SetInstructionBreakpointsResponseBody {
671 /// Information about the breakpoints. The array elements correspond to the
672 /// elements of the `breakpoints` array.
673 std::vector<Breakpoint> breakpoints;
674};
675llvm::json::Value toJSON(const SetInstructionBreakpointsResponseBody &);
676
677/// Arguments for `dataBreakpointInfo` request.
678struct DataBreakpointInfoArguments {
679 /// Reference to the variable container if the data breakpoint is requested
680 /// for a child of the container. The `variablesReference` must have been
681 /// obtained in the current suspended state.See 'Lifetime of Object
682 /// References' in the Overview section for details.
683 std::optional<int64_t> variablesReference;
684
685 /// The name of the variable's child to obtain data breakpoint information
686 /// for. If `variablesReference` isn't specified, this can be an expression,
687 /// or an address if `asAddress` is also true.
688 std::string name;
689
690 /// When `name` is an expression, evaluate it in the scope of this stack
691 /// frame. If not specified, the expression is evaluated in the global scope.
692 /// When `asAddress` is true, the `frameId` is ignored.
693 std::optional<uint64_t> frameId;
694
695 /// If specified, a debug adapter should return information for the range of
696 /// memory extending `bytes` number of bytes from the address or variable
697 /// specified by `name`. Breakpoints set using the resulting data ID should
698 /// pause on data access anywhere within that range.
699 /// Clients may set this property only if the `supportsDataBreakpointBytes`
700 /// capability is true.
701 std::optional<int64_t> bytes;
702
703 /// If `true`, the `name` is a memory address and the debugger should
704 /// interpret it as a decimal value, or hex value if it is prefixed with `0x`.
705 /// Clients may set this property only if the `supportsDataBreakpointBytes`
706 /// capability is true.
707 std::optional<bool> asAddress;
708
709 /// The mode of the desired breakpoint. If defined, this must be one of the
710 /// `breakpointModes` the debug adapter advertised in its `Capabilities`.
711 std::optional<std::string> mode;
712};
713bool fromJSON(const llvm::json::Value &, DataBreakpointInfoArguments &,
714 llvm::json::Path);
715
716/// Response to `dataBreakpointInfo` request.
717struct DataBreakpointInfoResponseBody {
718 /// An identifier for the data on which a data breakpoint can be registered
719 /// with the `setDataBreakpoints` request or null if no data breakpoint is
720 /// available. If a `variablesReference` or `frameId` is passed, the `dataId`
721 /// is valid in the current suspended state, otherwise it's valid
722 /// indefinitely. See 'Lifetime of Object References' in the Overview section
723 /// for details. Breakpoints set using the `dataId` in the
724 /// `setDataBreakpoints` request may outlive the lifetime of the associated
725 /// `dataId`.
726 std::optional<std::string> dataId;
727
728 /// UI string that describes on what data the breakpoint is set on or why a
729 /// data breakpoint is not available.
730 std::string description;
731
732 /// Attribute lists the available access types for a potential data
733 /// breakpoint. A UI client could surface this information.
734 std::optional<std::vector<DataBreakpointAccessType>> accessTypes;
735
736 /// Attribute indicates that a potential data breakpoint could be persisted
737 /// across sessions.
738 std::optional<bool> canPersist;
739};
740llvm::json::Value toJSON(const DataBreakpointInfoResponseBody &);
741
742/// Arguments for `setDataBreakpoints` request.
743struct SetDataBreakpointsArguments {
744 /// The contents of this array replaces all existing data breakpoints. An
745 /// empty array clears all data breakpoints.
746 std::vector<DataBreakpoint> breakpoints;
747};
748bool fromJSON(const llvm::json::Value &, SetDataBreakpointsArguments &,
749 llvm::json::Path);
750
751/// Response to `setDataBreakpoints` request.
752struct SetDataBreakpointsResponseBody {
753 /// Information about the data breakpoints. The array elements correspond to
754 /// the elements of the input argument `breakpoints` array.
755 std::vector<Breakpoint> breakpoints;
756};
757llvm::json::Value toJSON(const SetDataBreakpointsResponseBody &);
758
759/// Arguments for `setExceptionBreakpoints` request.
760struct SetExceptionBreakpointsArguments {
761 /// Set of exception filters specified by their ID. The set of all possible
762 /// exception filters is defined by the `exceptionBreakpointFilters`
763 /// capability. The `filter` and `filterOptions` sets are additive.
764 std::vector<std::string> filters;
765
766 /// Set of exception filters and their options. The set of all possible
767 /// exception filters is defined by the `exceptionBreakpointFilters`
768 /// capability. This attribute is only honored by a debug adapter if the
769 /// corresponding capability `supportsExceptionFilterOptions` is true. The
770 /// `filter` and `filterOptions` sets are additive.
771 std::vector<ExceptionFilterOptions> filterOptions;
772
773 // unsupported keys: exceptionOptions
774};
775bool fromJSON(const llvm::json::Value &, SetExceptionBreakpointsArguments &,
776 llvm::json::Path);
777
778/// Response to `setExceptionBreakpoints` request.
779///
780/// The response contains an array of `Breakpoint` objects with information
781/// about each exception breakpoint or filter. The `Breakpoint` objects are in
782/// the same order as the elements of the `filters`, `filterOptions`,
783/// `exceptionOptions` arrays given as arguments. If both `filters` and
784/// `filterOptions` are given, the returned array must start with `filters`
785/// information first, followed by `filterOptions` information.
786///
787/// The `verified` property of a `Breakpoint` object signals whether the
788/// exception breakpoint or filter could be successfully created and whether the
789/// condition is valid. In case of an error the `message` property explains the
790/// problem. The `id` property can be used to introduce a unique ID for the
791/// exception breakpoint or filter so that it can be updated subsequently by
792/// sending breakpoint events.
793///
794/// For backward compatibility both the `breakpoints` array and the enclosing
795/// `body` are optional. If these elements are missing a client is not able to
796/// show problems for individual exception breakpoints or filters.
797struct SetExceptionBreakpointsResponseBody {
798 /// Information about the exception breakpoints or filters.
799 ///
800 /// The breakpoints returned are in the same order as the elements of the
801 /// `filters`, `filterOptions`, `exceptionOptions` arrays in the arguments. If
802 /// both `filters` and `filterOptions` are given, the returned array must
803 /// start with `filters` information first, followed by `filterOptions`
804 /// information.
805 std::vector<Breakpoint> breakpoints;
806};
807llvm::json::Value toJSON(const SetExceptionBreakpointsResponseBody &);
808
809/// Arguments to `disassemble` request.
810struct DisassembleArguments {
811 /// Memory reference to the base location containing the instructions to
812 /// disassemble.
813 lldb::addr_t memoryReference = LLDB_INVALID_ADDRESS;
814
815 /// Offset (in bytes) to be applied to the reference location before
816 /// disassembling. Can be negative.
817 int64_t offset = 0;
818
819 /// Offset (in instructions) to be applied after the byte offset (if any)
820 /// before disassembling. Can be negative.
821 int64_t instructionOffset = 0;
822
823 /// Number of instructions to disassemble starting at the specified location
824 /// and offset.
825 /// An adapter must return exactly this number of instructions - any
826 /// unavailable instructions should be replaced with an implementation-defined
827 /// 'invalid instruction' value.
828 uint32_t instructionCount = 0;
829
830 /// If true, the adapter should attempt to resolve memory addresses and other
831 /// values to symbolic names.
832 bool resolveSymbols = false;
833};
834bool fromJSON(const llvm::json::Value &, DisassembleArguments &,
835 llvm::json::Path);
836llvm::json::Value toJSON(const DisassembleArguments &);
837
838/// Response to `disassemble` request.
839struct DisassembleResponseBody {
840 /// The list of disassembled instructions.
841 std::vector<DisassembledInstruction> instructions;
842};
843bool fromJSON(const llvm::json::Value &, DisassembleResponseBody &,
844 llvm::json::Path);
845llvm::json::Value toJSON(const DisassembleResponseBody &);
846
847/// Arguments for `readMemory` request.
848struct ReadMemoryArguments {
849 /// Memory reference to the base location from which data should be read.
850 lldb::addr_t memoryReference = LLDB_INVALID_ADDRESS;
851
852 /// Offset (in bytes) to be applied to the reference location before reading
853 /// data. Can be negative.
854 int64_t offset = 0;
855
856 /// Number of bytes to read at the specified location and offset.
857 uint64_t count = 0;
858};
859bool fromJSON(const llvm::json::Value &, ReadMemoryArguments &,
860 llvm::json::Path);
861
862/// Response to `readMemory` request.
863struct ReadMemoryResponseBody {
864 /// The address of the first byte of data returned.
865 /// Treated as a hex value if prefixed with `0x`, or as a decimal value
866 /// otherwise.
867 lldb::addr_t address = LLDB_INVALID_ADDRESS;
868
869 /// The number of unreadable bytes encountered after the last successfully
870 /// read byte.
871 /// This can be used to determine the number of bytes that should be skipped
872 /// before a subsequent `readMemory` request succeeds.
873 uint64_t unreadableBytes = 0;
874
875 /// The bytes read from memory, encoded using base64. If the decoded length
876 /// of `data` is less than the requested `count` in the original `readMemory`
877 /// request, and `unreadableBytes` is zero or omitted, then the client should
878 /// assume it's reached the end of readable memory.
879 std::vector<std::byte> data;
880};
881llvm::json::Value toJSON(const ReadMemoryResponseBody &);
882
883/// Arguments for `modules` request.
884struct ModulesArguments {
885 /// The index of the first module to return; if omitted modules start at 0.
886 uint32_t startModule = 0;
887
888 /// The number of modules to return. If `moduleCount` is not specified or 0,
889 /// all modules are returned.
890 uint32_t moduleCount = 0;
891};
892bool fromJSON(const llvm::json::Value &, ModulesArguments &, llvm::json::Path);
893
894/// Response to `modules` request.
895struct ModulesResponseBody {
896 /// All modules or range of modules.
897 std::vector<Module> modules;
898
899 /// The total number of modules available.
900 uint32_t totalModules = 0;
901};
902llvm::json::Value toJSON(const ModulesResponseBody &);
903
904/// Arguments for `variables` request.
905struct VariablesArguments {
906 /// The variable for which to retrieve its children. The `variablesReference`
907 /// must have been obtained in the current suspended state. See 'Lifetime of
908 /// Object References' in the Overview section for details.
909 uint64_t variablesReference;
910
911 enum VariablesFilter : unsigned {
912 eVariablesFilterBoth = 0,
913 eVariablesFilterIndexed = 1 << 0,
914 eVariablesFilterNamed = 1 << 1,
915 };
916
917 /// Filter to limit the child variables to either named or indexed. If
918 /// omitted, both types are fetched.
919 VariablesFilter filter = eVariablesFilterBoth;
920
921 /// The index of the first variable to return; if omitted children start at 0.
922 ///
923 /// The attribute is only honored by a debug adapter if the corresponding
924 /// capability `supportsVariablePaging` is true.
925 uint64_t start = 0;
926
927 /// The number of variables to return. If count is missing or 0, all variables
928 /// are returned.
929 ///
930 /// The attribute is only honored by a debug adapter if the corresponding
931 /// capability `supportsVariablePaging` is true.
932 uint64_t count = 0;
933
934 /// Specifies details on how to format the Variable values.
935 ///
936 /// The attribute is only honored by a debug adapter if the corresponding
937 /// capability `supportsValueFormattingOptions` is true.
938 std::optional<ValueFormat> format;
939};
940bool fromJSON(const llvm::json::Value &Param,
941 VariablesArguments::VariablesFilter &VA, llvm::json::Path Path);
942bool fromJSON(const llvm::json::Value &, VariablesArguments &,
943 llvm::json::Path);
944
945/// Response to `variables` request.
946struct VariablesResponseBody {
947 /// All (or a range) of variables for the given variable reference.
948 std::vector<Variable> variables;
949};
950llvm::json::Value toJSON(const VariablesResponseBody &);
951
952/// Arguments for `writeMemory` request.
953struct WriteMemoryArguments {
954 /// Memory reference to the base location to which data should be written.
955 lldb::addr_t memoryReference = LLDB_INVALID_ADDRESS;
956
957 /// Offset (in bytes) to be applied to the reference location before writing
958 /// data. Can be negative.
959 int64_t offset = 0;
960
961 /// Property to control partial writes. If true, the debug adapter should
962 /// attempt to write memory even if the entire memory region is not writable.
963 /// In such a case the debug adapter should stop after hitting the first byte
964 /// of memory that cannot be written and return the number of bytes written in
965 /// the response via the `offset` and `bytesWritten` properties.
966 /// If false or missing, a debug adapter should attempt to verify the region
967 /// is writable before writing, and fail the response if it is not.
968 bool allowPartial = false;
969
970 /// Bytes to write, encoded using base64.
971 std::string data;
972};
973bool fromJSON(const llvm::json::Value &, WriteMemoryArguments &,
974 llvm::json::Path);
975
976/// Response to writeMemory request.
977struct WriteMemoryResponseBody {
978 /// Property that should be returned when `allowPartial` is true to indicate
979 /// the number of bytes starting from address that were successfully written.
980 uint64_t bytesWritten = 0;
981};
982llvm::json::Value toJSON(const WriteMemoryResponseBody &);
983
984} // namespace lldb_dap::protocol
985
986#endif
987

source code of lldb/tools/lldb-dap/Protocol/ProtocolRequests.h