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_TYPES_H
21#define LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_TYPES_H
22
23#include "lldb/lldb-defines.h"
24#include "llvm/ADT/DenseSet.h"
25#include "llvm/Support/JSON.h"
26#include <cstdint>
27#include <optional>
28#include <string>
29
30#define LLDB_DAP_INVALID_VARRERF UINT64_MAX
31#define LLDB_DAP_INVALID_SRC_REF 0
32
33namespace lldb_dap::protocol {
34
35/// An `ExceptionBreakpointsFilter` is shown in the UI as an filter option for
36/// configuring how exceptions are dealt with.
37struct ExceptionBreakpointsFilter {
38 /// The internal ID of the filter option. This value is passed to the
39 /// `setExceptionBreakpoints` request.
40 std::string filter;
41
42 /// The name of the filter option. This is shown in the UI.
43 std::string label;
44
45 /// A help text providing additional information about the exception filter.
46 /// This string is typically shown as a hover and can be translated.
47 std::string description;
48
49 /// Initial value of the filter option. If not specified a value false is
50 /// assumed.
51 bool defaultState = false;
52
53 /// Controls whether a condition can be specified for this filter option. If
54 /// false or missing, a condition can not be set.
55 bool supportsCondition = false;
56
57 /// A help text providing information about the condition. This string is
58 /// shown as the placeholder text for a text box and can be translated.
59 std::string conditionDescription;
60};
61bool fromJSON(const llvm::json::Value &, ExceptionBreakpointsFilter &,
62 llvm::json::Path);
63llvm::json::Value toJSON(const ExceptionBreakpointsFilter &);
64
65enum ColumnType : unsigned {
66 eColumnTypeString,
67 eColumnTypeNumber,
68 eColumnTypeBoolean,
69 eColumnTypeTimestamp
70};
71bool fromJSON(const llvm::json::Value &, ColumnType &, llvm::json::Path);
72llvm::json::Value toJSON(const ColumnType &);
73
74/// A ColumnDescriptor specifies what module attribute to show in a column of
75/// the modules view, how to format it, and what the column’s label should be.
76///
77/// It is only used if the underlying UI actually supports this level of
78/// customization.
79struct ColumnDescriptor {
80 /// Name of the attribute rendered in this column.
81 std::string attributeName;
82
83 /// Header UI label of column.
84 std::string label;
85
86 /// Format to use for the rendered values in this column. TBD how the format
87 /// strings looks like.
88 std::optional<std::string> format;
89
90 /// Datatype of values in this column. Defaults to `string` if not specified.
91 /// Values: 'string', 'number', 'boolean', 'unixTimestampUTC'.
92 std::optional<ColumnType> type;
93
94 /// Width of this column in characters (hint only).
95 std::optional<int> width;
96};
97bool fromJSON(const llvm::json::Value &, ColumnDescriptor &, llvm::json::Path);
98llvm::json::Value toJSON(const ColumnDescriptor &);
99
100/// Names of checksum algorithms that may be supported by a debug adapter.
101/// Values: ‘MD5’, ‘SHA1’, ‘SHA256’, ‘timestamp’.
102enum ChecksumAlgorithm : unsigned {
103 eChecksumAlgorithmMD5,
104 eChecksumAlgorithmSHA1,
105 eChecksumAlgorithmSHA256,
106 eChecksumAlgorithmTimestamp
107};
108bool fromJSON(const llvm::json::Value &, ChecksumAlgorithm &, llvm::json::Path);
109llvm::json::Value toJSON(const ChecksumAlgorithm &);
110
111/// Describes one or more type of breakpoint a BreakpointMode applies to. This
112/// is a non-exhaustive enumeration and may expand as future breakpoint types
113/// are added.
114enum BreakpointModeApplicability : unsigned {
115 /// In `SourceBreakpoint`'s.
116 eBreakpointModeApplicabilitySource,
117 /// In exception breakpoints applied in the `ExceptionFilterOptions`.
118 eBreakpointModeApplicabilityException,
119 /// In data breakpoints requested in the `DataBreakpointInfo` request.
120 eBreakpointModeApplicabilityData,
121 /// In `InstructionBreakpoint`'s.
122 eBreakpointModeApplicabilityInstruction
123};
124bool fromJSON(const llvm::json::Value &, BreakpointModeApplicability &,
125 llvm::json::Path);
126llvm::json::Value toJSON(const BreakpointModeApplicability &);
127
128/// A `BreakpointMode` is provided as a option when setting breakpoints on
129/// sources or instructions.
130struct BreakpointMode {
131 /// The internal ID of the mode. This value is passed to the `setBreakpoints`
132 /// request.
133 std::string mode;
134
135 /// The name of the breakpoint mode. This is shown in the UI.
136 std::string label;
137
138 /// A help text providing additional information about the breakpoint mode.
139 /// This string is typically shown as a hover and can be translated.
140 std::optional<std::string> description;
141
142 /// Describes one or more type of breakpoint this mode applies to.
143 std::vector<BreakpointModeApplicability> appliesTo;
144};
145bool fromJSON(const llvm::json::Value &, BreakpointMode &, llvm::json::Path);
146llvm::json::Value toJSON(const BreakpointMode &);
147
148/// Debug Adapter Features flags supported by lldb-dap.
149enum AdapterFeature : unsigned {
150 /// The debug adapter supports ANSI escape sequences in styling of
151 /// `OutputEvent.output` and `Variable.value` fields.
152 eAdapterFeatureANSIStyling,
153 /// The debug adapter supports the `breakpointLocations` request.
154 eAdapterFeatureBreakpointLocationsRequest,
155 /// The debug adapter supports the `cancel` request.
156 eAdapterFeatureCancelRequest,
157 /// The debug adapter supports the `clipboard` context value in the
158 /// `evaluate` request.
159 eAdapterFeatureClipboardContext,
160 /// The debug adapter supports the `completions` request.
161 eAdapterFeatureCompletionsRequest,
162 /// The debug adapter supports conditional breakpoints.
163 eAdapterFeatureConditionalBreakpoints,
164 /// The debug adapter supports the `configurationDone` request.
165 eAdapterFeatureConfigurationDoneRequest,
166 /// The debug adapter supports the `asAddress` and `bytes` fields in the
167 /// `dataBreakpointInfo` request.
168 eAdapterFeatureDataBreakpointBytes,
169 /// The debug adapter supports data breakpoints.
170 eAdapterFeatureDataBreakpoints,
171 /// The debug adapter supports the delayed loading of parts of the stack,
172 /// which requires that both the `startFrame` and `levels` arguments and the
173 /// `totalFrames` result of the `stackTrace` request are supported.
174 eAdapterFeatureDelayedStackTraceLoading,
175 /// The debug adapter supports the `disassemble` request.
176 eAdapterFeatureDisassembleRequest,
177 /// The debug adapter supports a (side effect free) `evaluate` request for
178 /// data hovers.
179 eAdapterFeatureEvaluateForHovers,
180 /// The debug adapter supports `filterOptions` as an argument on the
181 /// `setExceptionBreakpoints` request.
182 eAdapterFeatureExceptionFilterOptions,
183 /// The debug adapter supports the `exceptionInfo` request.
184 eAdapterFeatureExceptionInfoRequest,
185 /// The debug adapter supports `exceptionOptions` on the
186 /// `setExceptionBreakpoints` request.
187 eAdapterFeatureExceptionOptions,
188 /// The debug adapter supports function breakpoints.
189 eAdapterFeatureFunctionBreakpoints,
190 /// The debug adapter supports the `gotoTargets` request.
191 eAdapterFeatureGotoTargetsRequest,
192 /// The debug adapter supports breakpoints that break execution after a
193 /// specified number of hits.
194 eAdapterFeatureHitConditionalBreakpoints,
195 /// The debug adapter supports adding breakpoints based on instruction
196 /// references.
197 eAdapterFeatureInstructionBreakpoints,
198 /// The debug adapter supports the `loadedSources` request.
199 eAdapterFeatureLoadedSourcesRequest,
200 /// The debug adapter supports log points by interpreting the `logMessage`
201 /// attribute of the `SourceBreakpoint`.
202 eAdapterFeatureLogPoints,
203 /// The debug adapter supports the `modules` request.
204 eAdapterFeatureModulesRequest,
205 /// The debug adapter supports the `readMemory` request.
206 eAdapterFeatureReadMemoryRequest,
207 /// The debug adapter supports restarting a frame.
208 eAdapterFeatureRestartFrame,
209 /// The debug adapter supports the `restart` request. In this case a client
210 /// should not implement `restart` by terminating and relaunching the
211 /// adapter but by calling the `restart` request.
212 eAdapterFeatureRestartRequest,
213 /// The debug adapter supports the `setExpression` request.
214 eAdapterFeatureSetExpression,
215 /// The debug adapter supports setting a variable to a value.
216 eAdapterFeatureSetVariable,
217 /// The debug adapter supports the `singleThread` property on the execution
218 /// requests (`continue`, `next`, `stepIn`, `stepOut`, `reverseContinue`,
219 /// `stepBack`).
220 eAdapterFeatureSingleThreadExecutionRequests,
221 /// The debug adapter supports stepping back via the `stepBack` and
222 /// `reverseContinue` requests.
223 eAdapterFeatureStepBack,
224 /// The debug adapter supports the `stepInTargets` request.
225 eAdapterFeatureStepInTargetsRequest,
226 /// The debug adapter supports stepping granularities (argument
227 /// `granularity`) for the stepping requests.
228 eAdapterFeatureSteppingGranularity,
229 /// The debug adapter supports the `terminate` request.
230 eAdapterFeatureTerminateRequest,
231 /// The debug adapter supports the `terminateThreads` request.
232 eAdapterFeatureTerminateThreadsRequest,
233 /// The debug adapter supports the `suspendDebuggee` attribute on the
234 /// `disconnect` request.
235 eAdapterFeatureSuspendDebuggee,
236 /// The debug adapter supports a `format` attribute on the `stackTrace`,
237 /// `variables`, and `evaluate` requests.
238 eAdapterFeatureValueFormattingOptions,
239 /// The debug adapter supports the `writeMemory` request.
240 eAdapterFeatureWriteMemoryRequest,
241 /// The debug adapter supports the `terminateDebuggee` attribute on the
242 /// `disconnect` request.
243 eAdapterFeatureTerminateDebuggee,
244 eAdapterFeatureFirst = eAdapterFeatureANSIStyling,
245 eAdapterFeatureLast = eAdapterFeatureTerminateDebuggee,
246};
247bool fromJSON(const llvm::json::Value &, AdapterFeature &, llvm::json::Path);
248llvm::json::Value toJSON(const AdapterFeature &);
249
250/// Information about the capabilities of a debug adapter.
251struct Capabilities {
252 /// The supported features for this adapter.
253 llvm::DenseSet<AdapterFeature> supportedFeatures;
254
255 /// Available exception filter options for the `setExceptionBreakpoints`
256 /// request.
257 std::vector<ExceptionBreakpointsFilter> exceptionBreakpointFilters;
258
259 /// The set of characters that should trigger completion in a REPL. If not
260 /// specified, the UI should assume the `.` character.
261 std::vector<std::string> completionTriggerCharacters;
262
263 /// The set of additional module information exposed by the debug adapter.
264 std::vector<ColumnDescriptor> additionalModuleColumns;
265
266 /// Checksum algorithms supported by the debug adapter.
267 std::vector<ChecksumAlgorithm> supportedChecksumAlgorithms;
268
269 /// Modes of breakpoints supported by the debug adapter, such as 'hardware' or
270 /// 'software'. If present, the client may allow the user to select a mode and
271 /// include it in its `setBreakpoints` request.
272 ///
273 /// Clients may present the first applicable mode in this array as the
274 /// 'default' mode in gestures that set breakpoints.
275 std::vector<BreakpointMode> breakpointModes;
276
277 /// lldb-dap Extensions
278 /// @{
279
280 /// The version of the adapter.
281 std::string lldbExtVersion;
282
283 /// @}
284};
285bool fromJSON(const llvm::json::Value &, Capabilities &, llvm::json::Path);
286llvm::json::Value toJSON(const Capabilities &);
287
288/// An `ExceptionFilterOptions` is used to specify an exception filter together
289/// with a condition for the `setExceptionBreakpoints` request.
290struct ExceptionFilterOptions {
291 /// ID of an exception filter returned by the `exceptionBreakpointFilters`
292 /// capability.
293 std::string filterId;
294
295 /// An expression for conditional exceptions.
296 /// The exception breaks into the debugger if the result of the condition is
297 /// true.
298 std::string condition;
299
300 /// The mode of this exception breakpoint. If defined, this must be one of the
301 /// `breakpointModes` the debug adapter advertised in its `Capabilities`.
302 std::string mode;
303};
304bool fromJSON(const llvm::json::Value &, ExceptionFilterOptions &,
305 llvm::json::Path);
306llvm::json::Value toJSON(const ExceptionFilterOptions &);
307
308/// A `Source` is a descriptor for source code. It is returned from the debug
309/// adapter as part of a `StackFrame` and it is used by clients when specifying
310/// breakpoints.
311struct Source {
312 enum PresentationHint : unsigned {
313 eSourcePresentationHintNormal,
314 eSourcePresentationHintEmphasize,
315 eSourcePresentationHintDeemphasize,
316 };
317
318 /// The short name of the source. Every source returned from the debug adapter
319 /// has a name. When sending a source to the debug adapter this name is
320 /// optional.
321 std::optional<std::string> name;
322
323 /// The path of the source to be shown in the UI. It is only used to locate
324 /// and load the content of the source if no `sourceReference` is specified
325 /// (or its value is 0).
326 std::optional<std::string> path;
327
328 /// If the value > 0 the contents of the source must be retrieved through the
329 /// `source` request (even if a path is specified). Since a `sourceReference`
330 /// is only valid for a session, it can not be used to persist a source. The
331 /// value should be less than or equal to 2147483647 (2^31-1).
332 std::optional<int32_t> sourceReference;
333
334 /// A hint for how to present the source in the UI. A value of `deemphasize`
335 /// can be used to indicate that the source is not available or that it is
336 /// skipped on stepping.
337 std::optional<PresentationHint> presentationHint;
338
339 // unsupported keys: origin, sources, adapterData, checksums
340};
341bool fromJSON(const llvm::json::Value &, Source::PresentationHint &,
342 llvm::json::Path);
343llvm::json::Value toJSON(Source::PresentationHint);
344bool fromJSON(const llvm::json::Value &, Source &, llvm::json::Path);
345llvm::json::Value toJSON(const Source &);
346
347/// A `Scope` is a named container for variables. Optionally a scope can map to
348/// a source or a range within a source.
349struct Scope {
350 enum PresentationHint : unsigned {
351 eScopePresentationHintArguments,
352 eScopePresentationHintLocals,
353 eScopePresentationHintRegisters,
354 eScopePresentationHintReturnValue
355 };
356 /// Name of the scope such as 'Arguments', 'Locals', or 'Registers'. This
357 /// string is shown in the UI as is and can be translated.
358 ////
359 std::string name;
360
361 /// A hint for how to present this scope in the UI. If this attribute is
362 /// missing, the scope is shown with a generic UI.
363 /// Values:
364 /// 'arguments': Scope contains method arguments.
365 /// 'locals': Scope contains local variables.
366 /// 'registers': Scope contains registers. Only a single `registers` scope
367 /// should be returned from a `scopes` request.
368 /// 'returnValue': Scope contains one or more return values.
369 /// etc.
370 std::optional<PresentationHint> presentationHint;
371
372 /// The variables of this scope can be retrieved by passing the value of
373 /// `variablesReference` to the `variables` request as long as execution
374 /// remains suspended. See 'Lifetime of Object References' in the Overview
375 /// section for details.
376 ////
377 uint64_t variablesReference = LLDB_DAP_INVALID_VARRERF;
378
379 /// The number of named variables in this scope.
380 /// The client can use this information to present the variables in a paged UI
381 /// and fetch them in chunks.
382 std::optional<uint64_t> namedVariables;
383
384 /// The number of indexed variables in this scope.
385 /// The client can use this information to present the variables in a paged UI
386 /// and fetch them in chunks.
387 std::optional<uint64_t> indexedVariables;
388
389 /// The source for this scope.
390 std::optional<Source> source;
391
392 /// If true, the number of variables in this scope is large or expensive to
393 /// retrieve.
394 bool expensive = false;
395
396 /// The start line of the range covered by this scope.
397 std::optional<uint64_t> line;
398
399 /// Start position of the range covered by the scope. It is measured in UTF-16
400 /// code units and the client capability `columnsStartAt1` determines whether
401 /// it is 0- or 1-based.
402 std::optional<uint64_t> column;
403
404 /// The end line of the range covered by this scope.
405 std::optional<uint64_t> endLine;
406
407 /// End position of the range covered by the scope. It is measured in UTF-16
408 /// code units and the client capability `columnsStartAt1` determines whether
409 /// it is 0- or 1-based.
410 std::optional<uint64_t> endColumn;
411};
412bool fromJSON(const llvm::json::Value &Params, Scope::PresentationHint &PH,
413 llvm::json::Path);
414bool fromJSON(const llvm::json::Value &, Scope &, llvm::json::Path);
415llvm::json::Value toJSON(const Scope &);
416
417/// The granularity of one `step` in the stepping requests `next`, `stepIn`,
418/// `stepOut` and `stepBack`.
419enum SteppingGranularity : unsigned {
420 /// The step should allow the program to run until the current statement has
421 /// finished executing. The meaning of a statement is determined by the
422 /// adapter and it may be considered equivalent to a line. For example
423 /// `for(int i = 0; i < 10; i++)` could be considered to have 3 statements
424 /// `int i = 0`, `i < 10`, and `i++`.
425 eSteppingGranularityStatement,
426 /// The step should allow the program to run until the current source line has
427 /// executed.
428 eSteppingGranularityLine,
429 /// The step should allow one instruction to execute (e.g. one x86
430 /// instruction).
431 eSteppingGranularityInstruction,
432};
433bool fromJSON(const llvm::json::Value &, SteppingGranularity &,
434 llvm::json::Path);
435llvm::json::Value toJSON(const SteppingGranularity &);
436
437/// A `StepInTarget` can be used in the `stepIn` request and determines into
438/// which single target the `stepIn` request should step.
439struct StepInTarget {
440 /// Unique identifier for a step-in target.
441 lldb::addr_t id = LLDB_INVALID_ADDRESS;
442
443 /// The name of the step-in target (shown in the UI).
444 std::string label;
445
446 /// The line of the step-in target.
447 uint32_t line = LLDB_INVALID_LINE_NUMBER;
448
449 /// Start position of the range covered by the step in target. It is measured
450 /// in UTF-16 code units and the client capability `columnsStartAt1`
451 /// determines whether it is 0- or 1-based.
452 uint32_t column = LLDB_INVALID_COLUMN_NUMBER;
453
454 /// The end line of the range covered by the step-in target.
455 uint32_t endLine = LLDB_INVALID_LINE_NUMBER;
456
457 /// End position of the range covered by the step in target. It is measured in
458 /// UTF-16 code units and the client capability `columnsStartAt1` determines
459 /// whether it is 0- or 1-based.
460 uint32_t endColumn = LLDB_INVALID_COLUMN_NUMBER;
461};
462bool fromJSON(const llvm::json::Value &, StepInTarget &, llvm::json::Path);
463llvm::json::Value toJSON(const StepInTarget &);
464
465/// A Thread.
466struct Thread {
467 /// Unique identifier for the thread.
468 lldb::tid_t id = LLDB_INVALID_THREAD_ID;
469 /// The name of the thread.
470 std::string name;
471};
472bool fromJSON(const llvm::json::Value &, Thread &, llvm::json::Path);
473llvm::json::Value toJSON(const Thread &);
474
475/// Provides formatting information for a value.
476struct ValueFormat {
477 /// Display the value in hex.
478 bool hex = false;
479};
480bool fromJSON(const llvm::json::Value &, ValueFormat &, llvm::json::Path);
481
482/// Properties of a breakpoint location returned from the `breakpointLocations`
483/// request.
484struct BreakpointLocation {
485 /// Start line of breakpoint location.
486 uint32_t line;
487
488 /// The start position of a breakpoint location. Position is measured in
489 /// UTF-16 code units and the client capability `columnsStartAt1` determines
490 /// whether it is 0- or 1-based.
491 std::optional<uint32_t> column;
492
493 /// The end line of breakpoint location if the location covers a range.
494 std::optional<uint32_t> endLine;
495
496 /// The end position of a breakpoint location (if the location covers a
497 /// range). Position is measured in UTF-16 code units and the client
498 /// capability `columnsStartAt1` determines whether it is 0- or 1-based.
499 std::optional<uint32_t> endColumn;
500};
501llvm::json::Value toJSON(const BreakpointLocation &);
502
503/// A machine-readable explanation of why a breakpoint may not be verified.
504enum class BreakpointReason : unsigned {
505 /// Indicates a breakpoint might be verified in the future, but
506 /// the adapter cannot verify it in the current state.
507 eBreakpointReasonPending,
508 /// Indicates a breakpoint was not able to be verified, and the
509 /// adapter does not believe it can be verified without intervention.
510 eBreakpointReasonFailed,
511};
512bool fromJSON(const llvm::json::Value &, BreakpointReason &, llvm::json::Path);
513llvm::json::Value toJSON(const BreakpointReason &);
514
515/// Information about a breakpoint created in `setBreakpoints`,
516/// `setFunctionBreakpoints`, `setInstructionBreakpoints`, or
517/// `setDataBreakpoints` requests.
518struct Breakpoint {
519 /// The identifier for the breakpoint. It is needed if breakpoint events are
520 /// used to update or remove breakpoints.
521 std::optional<int> id;
522
523 /// If true, the breakpoint could be set (but not necessarily at the desired
524 /// location).
525 bool verified = false;
526
527 /// A message about the state of the breakpoint.
528 /// This is shown to the user and can be used to explain why a breakpoint
529 /// could not be verified.
530 std::optional<std::string> message;
531
532 /// The source where the breakpoint is located.
533 std::optional<Source> source;
534
535 /// The start line of the actual range covered by the breakpoint.
536 std::optional<uint32_t> line;
537
538 /// Start position of the source range covered by the breakpoint. It is
539 /// measured in UTF-16 code units and the client capability `columnsStartAt1`
540 /// determines whether it is 0- or 1-based.
541 std::optional<uint32_t> column;
542
543 /// The end line of the actual range covered by the breakpoint.
544 std::optional<uint32_t> endLine;
545
546 /// End position of the source range covered by the breakpoint. It is measured
547 /// in UTF-16 code units and the client capability `columnsStartAt1`
548 /// determines whether it is 0- or 1-based. If no end line is given, then the
549 /// end column is assumed to be in the start line.
550 std::optional<uint32_t> endColumn;
551
552 /// A memory reference to where the breakpoint is set.
553 std::optional<std::string> instructionReference;
554
555 /// The offset from the instruction reference.
556 /// This can be negative.
557 std::optional<int32_t> offset;
558
559 /// A machine-readable explanation of why a breakpoint may not be verified. If
560 /// a breakpoint is verified or a specific reason is not known, the adapter
561 /// should omit this property.
562 std::optional<BreakpointReason> reason;
563};
564bool fromJSON(const llvm::json::Value &, Breakpoint &, llvm::json::Path);
565llvm::json::Value toJSON(const Breakpoint &);
566
567/// Properties of a breakpoint or logpoint passed to the `setBreakpoints`
568/// request
569struct SourceBreakpoint {
570 /// The source line of the breakpoint or logpoint.
571 uint32_t line = LLDB_INVALID_LINE_NUMBER;
572
573 /// Start position within source line of the breakpoint or logpoint. It is
574 /// measured in UTF-16 code units and the client capability `columnsStartAt1`
575 /// determines whether it is 0- or 1-based.
576 std::optional<uint32_t> column;
577
578 /// The expression for conditional breakpoints.
579 /// It is only honored by a debug adapter if the corresponding capability
580 /// `supportsConditionalBreakpoints` is true.
581 std::optional<std::string> condition;
582
583 /// The expression that controls how many hits of the breakpoint are ignored.
584 /// The debug adapter is expected to interpret the expression as needed.
585 /// The attribute is only honored by a debug adapter if the corresponding
586 /// capability `supportsHitConditionalBreakpoints` is true.
587 /// If both this property and `condition` are specified, `hitCondition` should
588 /// be evaluated only if the `condition` is met, and the debug adapter should
589 /// stop only if both conditions are met.
590 std::optional<std::string> hitCondition;
591
592 /// If this attribute exists and is non-empty, the debug adapter must not
593 /// 'break' (stop)
594 /// but log the message instead. Expressions within `{}` are interpolated.
595 /// The attribute is only honored by a debug adapter if the corresponding
596 /// capability `supportsLogPoints` is true.
597 /// If either `hitCondition` or `condition` is specified, then the message
598 /// should only be logged if those conditions are met.
599 std::optional<std::string> logMessage;
600
601 /// The mode of this breakpoint. If defined, this must be one of the
602 /// `breakpointModes` the debug adapter advertised in its `Capabilities`.
603 std::optional<std::string> mode;
604};
605bool fromJSON(const llvm::json::Value &, SourceBreakpoint &, llvm::json::Path);
606llvm::json::Value toJSON(const SourceBreakpoint &);
607
608/// Properties of a breakpoint passed to the `setFunctionBreakpoints` request.
609struct FunctionBreakpoint {
610 /// The name of the function.
611 std::string name;
612
613 /// An expression for conditional breakpoints.
614 /// It is only honored by a debug adapter if the corresponding capability
615 /// `supportsConditionalBreakpoints` is true.
616 std::optional<std::string> condition;
617
618 /// An expression that controls how many hits of the breakpoint are ignored.
619 /// The debug adapter is expected to interpret the expression as needed.
620 /// The attribute is only honored by a debug adapter if the corresponding
621 /// capability `supportsHitConditionalBreakpoints` is true.
622 std::optional<std::string> hitCondition;
623};
624bool fromJSON(const llvm::json::Value &, FunctionBreakpoint &,
625 llvm::json::Path);
626llvm::json::Value toJSON(const FunctionBreakpoint &);
627
628/// This enumeration defines all possible access types for data breakpoints.
629/// Values: ‘read’, ‘write’, ‘readWrite’
630enum DataBreakpointAccessType : unsigned {
631 eDataBreakpointAccessTypeRead,
632 eDataBreakpointAccessTypeWrite,
633 eDataBreakpointAccessTypeReadWrite
634};
635bool fromJSON(const llvm::json::Value &, DataBreakpointAccessType &,
636 llvm::json::Path);
637llvm::json::Value toJSON(const DataBreakpointAccessType &);
638
639/// Properties of a data breakpoint passed to the `setDataBreakpoints` request.
640struct DataBreakpoint {
641 /// An id representing the data. This id is returned from the
642 /// `dataBreakpointInfo` request.
643 std::string dataId;
644
645 /// The access type of the data.
646 std::optional<DataBreakpointAccessType> accessType;
647
648 /// An expression for conditional breakpoints.
649 std::optional<std::string> condition;
650
651 /// An expression that controls how many hits of the breakpoint are ignored.
652 /// The debug adapter is expected to interpret the expression as needed.
653 std::optional<std::string> hitCondition;
654};
655bool fromJSON(const llvm::json::Value &, DataBreakpoint &, llvm::json::Path);
656llvm::json::Value toJSON(const DataBreakpoint &);
657
658/// Properties of a breakpoint passed to the `setInstructionBreakpoints` request
659struct InstructionBreakpoint {
660 /// The instruction reference of the breakpoint.
661 /// This should be a memory or instruction pointer reference from an
662 /// `EvaluateResponse`, `Variable`, `StackFrame`, `GotoTarget`, or
663 /// `Breakpoint`.
664 std::string instructionReference;
665
666 /// The offset from the instruction reference in bytes.
667 /// This can be negative.
668 std::optional<int32_t> offset;
669
670 /// An expression for conditional breakpoints.
671 /// It is only honored by a debug adapter if the corresponding capability
672 /// `supportsConditionalBreakpoints` is true.
673 std::optional<std::string> condition;
674
675 /// An expression that controls how many hits of the breakpoint are ignored.
676 /// The debug adapter is expected to interpret the expression as needed.
677 /// The attribute is only honored by a debug adapter if the corresponding
678 /// capability `supportsHitConditionalBreakpoints` is true.
679 std::optional<std::string> hitCondition;
680
681 /// The mode of this breakpoint. If defined, this must be one of the
682 /// `breakpointModes` the debug adapter advertised in its `Capabilities`.
683 std::optional<std::string> mode;
684};
685bool fromJSON(const llvm::json::Value &, InstructionBreakpoint &,
686 llvm::json::Path);
687
688/// Properties of a single disassembled instruction, returned by `disassemble`
689/// request.
690struct DisassembledInstruction {
691 enum PresentationHint : unsigned {
692 eDisassembledInstructionPresentationHintNormal,
693 eDisassembledInstructionPresentationHintInvalid,
694 };
695
696 /// The address of the instruction. Treated as a hex value if prefixed with
697 /// `0x`, or as a decimal value otherwise.
698 lldb::addr_t address = LLDB_INVALID_ADDRESS;
699
700 /// Raw bytes representing the instruction and its operands, in an
701 /// implementation-defined format.
702 std::optional<std::string> instructionBytes;
703
704 /// Text representing the instruction and its operands, in an
705 /// implementation-defined format.
706 std::string instruction;
707
708 /// Name of the symbol that corresponds with the location of this instruction,
709 /// if any.
710 std::optional<std::string> symbol;
711
712 /// Source location that corresponds to this instruction, if any.
713 /// Should always be set (if available) on the first instruction returned,
714 /// but can be omitted afterwards if this instruction maps to the same source
715 /// file as the previous instruction.
716 std::optional<protocol::Source> location;
717
718 /// The line within the source location that corresponds to this instruction,
719 /// if any.
720 std::optional<uint32_t> line;
721
722 /// The column within the line that corresponds to this instruction, if any.
723 std::optional<uint32_t> column;
724
725 /// The end line of the range that corresponds to this instruction, if any.
726 std::optional<uint32_t> endLine;
727
728 /// The end column of the range that corresponds to this instruction, if any.
729 std::optional<uint32_t> endColumn;
730
731 /// A hint for how to present the instruction in the UI.
732 ///
733 /// A value of `invalid` may be used to indicate this instruction is 'filler'
734 /// and cannot be reached by the program. For example, unreadable memory
735 /// addresses may be presented is 'invalid.'
736 /// Values: 'normal', 'invalid'
737 std::optional<PresentationHint> presentationHint;
738};
739bool fromJSON(const llvm::json::Value &,
740 DisassembledInstruction::PresentationHint &, llvm::json::Path);
741llvm::json::Value toJSON(const DisassembledInstruction::PresentationHint &);
742bool fromJSON(const llvm::json::Value &, DisassembledInstruction &,
743 llvm::json::Path);
744llvm::json::Value toJSON(const DisassembledInstruction &);
745
746struct Module {
747 /// Unique identifier for the module.
748 std::string id;
749
750 /// A name of the module.
751 std::string name;
752
753 /// Logical full path to the module. The exact definition is implementation
754 /// defined, but usually this would be a full path to the on-disk file for the
755 /// module.
756 std::string path;
757
758 /// True if the module is optimized.
759 bool isOptimized = false;
760
761 /// True if the module is considered 'user code' by a debugger that supports
762 /// 'Just My Code'.
763 bool isUserCode = false;
764
765 /// Version of Module.
766 std::string version;
767
768 /// User-understandable description of if symbols were found for the module
769 /// (ex: 'Symbols Loaded', 'Symbols not found', etc.)
770 std::string symbolStatus;
771
772 /// Logical full path to the symbol file. The exact definition is
773 /// implementation defined.
774 std::string symbolFilePath;
775
776 /// Module created or modified, encoded as an RFC 3339 timestamp.
777 std::string dateTimeStamp;
778
779 /// Address range covered by this module.
780 std::string addressRange;
781
782 /// Custom fields
783 /// @{
784
785 /// Size of the debug_info sections in the module in bytes.
786 uint64_t debugInfoSizeBytes = 0;
787
788 //// @}
789};
790llvm::json::Value toJSON(const Module &);
791
792/// Properties of a variable that can be used to determine how to render the
793/// variable in the UI.
794struct VariablePresentationHint {
795 /// The kind of variable. Before introducing additional values, try to use the
796 /// listed values.
797 std::string kind;
798
799 /// Set of attributes represented as an array of strings. Before introducing
800 /// additional values, try to use the listed values.
801 std::vector<std::string> attributes;
802
803 /// Visibility of variable. Before introducing additional values, try to use
804 /// the listed values.
805 std::string visibility;
806
807 /// If true, clients can present the variable with a UI that supports a
808 /// specific gesture to trigger its evaluation.
809 ///
810 /// This mechanism can be used for properties that require executing code when
811 /// retrieving their value and where the code execution can be expensive
812 /// and/or produce side-effects. A typical example are properties based on a
813 /// getter function.
814 ///
815 /// Please note that in addition to the `lazy` flag, the variable's
816 /// `variablesReference` is expected to refer to a variable that will provide
817 /// the value through another `variable` request.
818 bool lazy = false;
819};
820llvm::json::Value toJSON(const VariablePresentationHint &);
821bool fromJSON(const llvm::json::Value &, VariablePresentationHint &,
822 llvm::json::Path);
823
824/// A Variable is a name/value pair.
825///
826/// The `type` attribute is shown if space permits or when hovering over the
827/// variable's name.
828///
829/// The `kind` attribute is used to render additional properties of the
830/// variable, e.g. different icons can be used to indicate that a variable is
831/// public or private.
832///
833/// If the value is structured (has children), a handle is provided to retrieve
834/// the children with the `variables` request.
835///
836/// If the number of named or indexed children is large, the numbers should be
837/// returned via the `namedVariables` and `indexedVariables` attributes.
838///
839/// The client can use this information to present the children in a paged UI
840/// and fetch them in chunks.
841struct Variable {
842 /// The variable's name.
843 std::string name;
844
845 /// The variable's value.
846 ///
847 /// This can be a multi-line text, e.g. for a function the body of a function.
848 ///
849 /// For structured variables (which do not have a simple value), it is
850 /// recommended to provide a one-line representation of the structured object.
851 /// This helps to identify the structured object in the collapsed state when
852 /// its children are not yet visible.
853 ///
854 /// An empty string can be used if no value should be shown in the UI.
855 std::string value;
856
857 /// The type of the variable's value. Typically shown in the UI when hovering
858 /// over the value.
859 ///
860 /// This attribute should only be returned by a debug adapter if the
861 /// corresponding capability `supportsVariableType` is true.
862 std::string type;
863
864 /// Properties of a variable that can be used to determine how to render the
865 /// variable in the UI.
866 std::optional<VariablePresentationHint> presentationHint;
867
868 /// The evaluatable name of this variable which can be passed to the
869 /// `evaluate` request to fetch the variable's value.
870 std::string evaluateName;
871
872 /// If `variablesReference` is > 0, the variable is structured and its
873 /// children can be retrieved by passing `variablesReference` to the
874 /// `variables` request as long as execution remains suspended. See 'Lifetime
875 /// of Object References' in the Overview section for details.
876 uint64_t variablesReference = 0;
877
878 /// The number of named child variables.
879 ///
880 /// The client can use this information to present the children in a paged UI
881 /// and fetch them in chunks.
882 uint64_t namedVariables = 0;
883
884 /// The number of indexed child variables.
885 ///
886 /// The client can use this information to present the children in a paged UI
887 /// and fetch them in chunks.
888 uint64_t indexedVariables = 0;
889
890 /// A memory reference associated with this variable.
891 ///
892 /// For pointer type variables, this is generally a reference to the memory
893 /// address contained in the pointer.
894 ///
895 /// For executable data, this reference may later be used in a `disassemble`
896 /// request.
897 ///
898 /// This attribute may be returned by a debug adapter if corresponding
899 /// capability `supportsMemoryReferences` is true.
900 lldb::addr_t memoryReference = LLDB_INVALID_ADDRESS;
901
902 /// A reference that allows the client to request the location where the
903 /// variable is declared. This should be present only if the adapter is likely
904 /// to be able to resolve the location.
905 ///
906 /// This reference shares the same lifetime as the `variablesReference`. See
907 /// 'Lifetime of Object References' in the Overview section for details.
908 uint64_t declarationLocationReference = 0;
909
910 /// A reference that allows the client to request the location where the
911 /// variable's value is declared. For example, if the variable contains a
912 /// function pointer, the adapter may be able to look up the function's
913 /// location. This should be present only if the adapter is likely to be able
914 /// to resolve the location.
915 ///
916 /// This reference shares the same lifetime as the `variablesReference`. See
917 /// 'Lifetime of Object References' in the Overview section for details.
918 uint64_t valueLocationReference = 0;
919};
920llvm::json::Value toJSON(const Variable &);
921bool fromJSON(const llvm::json::Value &, Variable &, llvm::json::Path);
922
923} // namespace lldb_dap::protocol
924
925#endif
926

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