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 | |
32 | namespace lldb_dap::protocol { |
33 | |
34 | /// An `ExceptionBreakpointsFilter` is shown in the UI as an filter option for |
35 | /// configuring how exceptions are dealt with. |
36 | struct ExceptionBreakpointsFilter { |
37 | /// The internal ID of the filter option. This value is passed to the |
38 | /// `setExceptionBreakpoints` request. |
39 | std::string filter; |
40 | |
41 | /// The name of the filter option. This is shown in the UI. |
42 | std::string label; |
43 | |
44 | /// A help text providing additional information about the exception filter. |
45 | /// This string is typically shown as a hover and can be translated. |
46 | std::optional<std::string> description; |
47 | |
48 | /// Initial value of the filter option. If not specified a value false is |
49 | /// assumed. |
50 | std::optional<bool> defaultState; |
51 | |
52 | /// Controls whether a condition can be specified for this filter option. If |
53 | /// false or missing, a condition can not be set. |
54 | std::optional<bool> supportsCondition; |
55 | |
56 | /// A help text providing information about the condition. This string is |
57 | /// shown as the placeholder text for a text box and can be translated. |
58 | std::optional<std::string> conditionDescription; |
59 | }; |
60 | bool fromJSON(const llvm::json::Value &, ExceptionBreakpointsFilter &, |
61 | llvm::json::Path); |
62 | llvm::json::Value toJSON(const ExceptionBreakpointsFilter &); |
63 | |
64 | enum ColumnType : unsigned { |
65 | eColumnTypeString, |
66 | eColumnTypeNumber, |
67 | eColumnTypeBoolean, |
68 | eColumnTypeTimestamp |
69 | }; |
70 | bool fromJSON(const llvm::json::Value &, ColumnType &, llvm::json::Path); |
71 | llvm::json::Value toJSON(const ColumnType &); |
72 | |
73 | /// A ColumnDescriptor specifies what module attribute to show in a column of |
74 | /// the modules view, how to format it, and what the column’s label should be. |
75 | /// |
76 | /// It is only used if the underlying UI actually supports this level of |
77 | /// customization. |
78 | struct ColumnDescriptor { |
79 | /// Name of the attribute rendered in this column. |
80 | std::string attributeName; |
81 | |
82 | /// Header UI label of column. |
83 | std::string label; |
84 | |
85 | /// Format to use for the rendered values in this column. TBD how the format |
86 | /// strings looks like. |
87 | std::optional<std::string> format; |
88 | |
89 | /// Datatype of values in this column. Defaults to `string` if not specified. |
90 | /// Values: 'string', 'number', 'boolean', 'unixTimestampUTC'. |
91 | std::optional<ColumnType> type; |
92 | |
93 | /// Width of this column in characters (hint only). |
94 | std::optional<int> width; |
95 | }; |
96 | bool fromJSON(const llvm::json::Value &, ColumnDescriptor &, llvm::json::Path); |
97 | llvm::json::Value toJSON(const ColumnDescriptor &); |
98 | |
99 | /// Names of checksum algorithms that may be supported by a debug adapter. |
100 | /// Values: ‘MD5’, ‘SHA1’, ‘SHA256’, ‘timestamp’. |
101 | enum ChecksumAlgorithm : unsigned { |
102 | eChecksumAlgorithmMD5, |
103 | eChecksumAlgorithmSHA1, |
104 | eChecksumAlgorithmSHA256, |
105 | eChecksumAlgorithmTimestamp |
106 | }; |
107 | bool fromJSON(const llvm::json::Value &, ChecksumAlgorithm &, llvm::json::Path); |
108 | llvm::json::Value toJSON(const ChecksumAlgorithm &); |
109 | |
110 | /// Describes one or more type of breakpoint a BreakpointMode applies to. This |
111 | /// is a non-exhaustive enumeration and may expand as future breakpoint types |
112 | /// are added. |
113 | enum BreakpointModeApplicability : unsigned { |
114 | /// In `SourceBreakpoint`'s. |
115 | eBreakpointModeApplicabilitySource, |
116 | /// In exception breakpoints applied in the `ExceptionFilterOptions`. |
117 | eBreakpointModeApplicabilityException, |
118 | /// In data breakpoints requested in the `DataBreakpointInfo` request. |
119 | eBreakpointModeApplicabilityData, |
120 | /// In `InstructionBreakpoint`'s. |
121 | eBreakpointModeApplicabilityInstruction |
122 | }; |
123 | bool fromJSON(const llvm::json::Value &, BreakpointModeApplicability &, |
124 | llvm::json::Path); |
125 | llvm::json::Value toJSON(const BreakpointModeApplicability &); |
126 | |
127 | /// A `BreakpointMode` is provided as a option when setting breakpoints on |
128 | /// sources or instructions. |
129 | struct BreakpointMode { |
130 | /// The internal ID of the mode. This value is passed to the `setBreakpoints` |
131 | /// request. |
132 | std::string mode; |
133 | |
134 | /// The name of the breakpoint mode. This is shown in the UI. |
135 | std::string label; |
136 | |
137 | /// A help text providing additional information about the breakpoint mode. |
138 | /// This string is typically shown as a hover and can be translated. |
139 | std::optional<std::string> description; |
140 | |
141 | /// Describes one or more type of breakpoint this mode applies to. |
142 | std::vector<BreakpointModeApplicability> appliesTo; |
143 | }; |
144 | bool fromJSON(const llvm::json::Value &, BreakpointMode &, llvm::json::Path); |
145 | llvm::json::Value toJSON(const BreakpointMode &); |
146 | |
147 | /// Debug Adapter Features flags supported by lldb-dap. |
148 | enum AdapterFeature : unsigned { |
149 | /// The debug adapter supports ANSI escape sequences in styling of |
150 | /// `OutputEvent.output` and `Variable.value` fields. |
151 | eAdapterFeatureANSIStyling, |
152 | /// The debug adapter supports the `breakpointLocations` request. |
153 | eAdapterFeatureBreakpointLocationsRequest, |
154 | /// The debug adapter supports the `cancel` request. |
155 | eAdapterFeatureCancelRequest, |
156 | /// The debug adapter supports the `clipboard` context value in the |
157 | /// `evaluate` request. |
158 | eAdapterFeatureClipboardContext, |
159 | /// The debug adapter supports the `completions` request. |
160 | eAdapterFeatureCompletionsRequest, |
161 | /// The debug adapter supports conditional breakpoints. |
162 | eAdapterFeatureConditionalBreakpoints, |
163 | /// The debug adapter supports the `configurationDone` request. |
164 | eAdapterFeatureConfigurationDoneRequest, |
165 | /// The debug adapter supports the `asAddress` and `bytes` fields in the |
166 | /// `dataBreakpointInfo` request. |
167 | eAdapterFeatureDataBreakpointBytes, |
168 | /// The debug adapter supports data breakpoints. |
169 | eAdapterFeatureDataBreakpoints, |
170 | /// The debug adapter supports the delayed loading of parts of the stack, |
171 | /// which requires that both the `startFrame` and `levels` arguments and the |
172 | /// `totalFrames` result of the `stackTrace` request are supported. |
173 | eAdapterFeatureDelayedStackTraceLoading, |
174 | /// The debug adapter supports the `disassemble` request. |
175 | eAdapterFeatureDisassembleRequest, |
176 | /// The debug adapter supports a (side effect free) `evaluate` request for |
177 | /// data hovers. |
178 | eAdapterFeatureEvaluateForHovers, |
179 | /// The debug adapter supports `filterOptions` as an argument on the |
180 | /// `setExceptionBreakpoints` request. |
181 | eAdapterFeatureExceptionFilterOptions, |
182 | /// The debug adapter supports the `exceptionInfo` request. |
183 | eAdapterFeatureExceptionInfoRequest, |
184 | /// The debug adapter supports `exceptionOptions` on the |
185 | /// `setExceptionBreakpoints` request. |
186 | eAdapterFeatureExceptionOptions, |
187 | /// The debug adapter supports function breakpoints. |
188 | eAdapterFeatureFunctionBreakpoints, |
189 | /// The debug adapter supports the `gotoTargets` request. |
190 | eAdapterFeatureGotoTargetsRequest, |
191 | /// The debug adapter supports breakpoints that break execution after a |
192 | /// specified number of hits. |
193 | eAdapterFeatureHitConditionalBreakpoints, |
194 | /// The debug adapter supports adding breakpoints based on instruction |
195 | /// references. |
196 | eAdapterFeatureInstructionBreakpoints, |
197 | /// The debug adapter supports the `loadedSources` request. |
198 | eAdapterFeatureLoadedSourcesRequest, |
199 | /// The debug adapter supports log points by interpreting the `logMessage` |
200 | /// attribute of the `SourceBreakpoint`. |
201 | eAdapterFeatureLogPoints, |
202 | /// The debug adapter supports the `modules` request. |
203 | eAdapterFeatureModulesRequest, |
204 | /// The debug adapter supports the `readMemory` request. |
205 | eAdapterFeatureReadMemoryRequest, |
206 | /// The debug adapter supports restarting a frame. |
207 | eAdapterFeatureRestartFrame, |
208 | /// The debug adapter supports the `restart` request. In this case a client |
209 | /// should not implement `restart` by terminating and relaunching the |
210 | /// adapter but by calling the `restart` request. |
211 | eAdapterFeatureRestartRequest, |
212 | /// The debug adapter supports the `setExpression` request. |
213 | eAdapterFeatureSetExpression, |
214 | /// The debug adapter supports setting a variable to a value. |
215 | eAdapterFeatureSetVariable, |
216 | /// The debug adapter supports the `singleThread` property on the execution |
217 | /// requests (`continue`, `next`, `stepIn`, `stepOut`, `reverseContinue`, |
218 | /// `stepBack`). |
219 | eAdapterFeatureSingleThreadExecutionRequests, |
220 | /// The debug adapter supports stepping back via the `stepBack` and |
221 | /// `reverseContinue` requests. |
222 | eAdapterFeatureStepBack, |
223 | /// The debug adapter supports the `stepInTargets` request. |
224 | eAdapterFeatureStepInTargetsRequest, |
225 | /// The debug adapter supports stepping granularities (argument |
226 | /// `granularity`) for the stepping requests. |
227 | eAdapterFeatureSteppingGranularity, |
228 | /// The debug adapter supports the `terminate` request. |
229 | eAdapterFeatureTerminateRequest, |
230 | /// The debug adapter supports the `terminateThreads` request. |
231 | eAdapterFeatureTerminateThreadsRequest, |
232 | /// The debug adapter supports the `suspendDebuggee` attribute on the |
233 | /// `disconnect` request. |
234 | eAdapterFeatureSuspendDebuggee, |
235 | /// The debug adapter supports a `format` attribute on the `stackTrace`, |
236 | /// `variables`, and `evaluate` requests. |
237 | eAdapterFeatureValueFormattingOptions, |
238 | /// The debug adapter supports the `writeMemory` request. |
239 | eAdapterFeatureWriteMemoryRequest, |
240 | /// The debug adapter supports the `terminateDebuggee` attribute on the |
241 | /// `disconnect` request. |
242 | eAdapterFeatureTerminateDebuggee, |
243 | eAdapterFeatureFirst = eAdapterFeatureANSIStyling, |
244 | eAdapterFeatureLast = eAdapterFeatureTerminateDebuggee, |
245 | }; |
246 | bool fromJSON(const llvm::json::Value &, AdapterFeature &, llvm::json::Path); |
247 | llvm::json::Value toJSON(const AdapterFeature &); |
248 | |
249 | /// Information about the capabilities of a debug adapter. |
250 | struct Capabilities { |
251 | /// The supported features for this adapter. |
252 | llvm::DenseSet<AdapterFeature> supportedFeatures; |
253 | |
254 | /// Available exception filter options for the `setExceptionBreakpoints` |
255 | /// request. |
256 | std::optional<std::vector<ExceptionBreakpointsFilter>> |
257 | 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::optional<std::vector<std::string>> completionTriggerCharacters; |
262 | |
263 | /// The set of additional module information exposed by the debug adapter. |
264 | std::optional<std::vector<ColumnDescriptor>> additionalModuleColumns; |
265 | |
266 | /// Checksum algorithms supported by the debug adapter. |
267 | std::optional<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::optional<std::vector<BreakpointMode>> breakpointModes; |
276 | |
277 | /// lldb-dap Extensions |
278 | /// @{ |
279 | |
280 | /// The version of the adapter. |
281 | std::optional<std::string> lldbExtVersion; |
282 | |
283 | /// @} |
284 | }; |
285 | bool fromJSON(const llvm::json::Value &, Capabilities &, llvm::json::Path); |
286 | llvm::json::Value toJSON(const Capabilities &); |
287 | |
288 | /// A `Source` is a descriptor for source code. It is returned from the debug |
289 | /// adapter as part of a `StackFrame` and it is used by clients when specifying |
290 | /// breakpoints. |
291 | struct Source { |
292 | enum PresentationHint : unsigned { |
293 | eSourcePresentationHintNormal, |
294 | eSourcePresentationHintEmphasize, |
295 | eSourcePresentationHintDeemphasize, |
296 | }; |
297 | |
298 | /// The short name of the source. Every source returned from the debug adapter |
299 | /// has a name. When sending a source to the debug adapter this name is |
300 | /// optional. |
301 | std::optional<std::string> name; |
302 | |
303 | /// The path of the source to be shown in the UI. It is only used to locate |
304 | /// and load the content of the source if no `sourceReference` is specified |
305 | /// (or its value is 0). |
306 | std::optional<std::string> path; |
307 | |
308 | /// If the value > 0 the contents of the source must be retrieved through the |
309 | /// `source` request (even if a path is specified). Since a `sourceReference` |
310 | /// is only valid for a session, it can not be used to persist a source. The |
311 | /// value should be less than or equal to 2147483647 (2^31-1). |
312 | std::optional<int64_t> sourceReference; |
313 | |
314 | /// A hint for how to present the source in the UI. A value of `deemphasize` |
315 | /// can be used to indicate that the source is not available or that it is |
316 | /// skipped on stepping. |
317 | std::optional<PresentationHint> presentationHint; |
318 | |
319 | // unsupported keys: origin, sources, adapterData, checksums |
320 | }; |
321 | bool fromJSON(const llvm::json::Value &, Source::PresentationHint &, |
322 | llvm::json::Path); |
323 | llvm::json::Value toJSON(Source::PresentationHint); |
324 | bool fromJSON(const llvm::json::Value &, Source &, llvm::json::Path); |
325 | llvm::json::Value toJSON(const Source &); |
326 | |
327 | /// A `Scope` is a named container for variables. Optionally a scope can map to |
328 | /// a source or a range within a source. |
329 | struct Scope { |
330 | enum PresentationHint : unsigned { |
331 | eScopePresentationHintArguments, |
332 | eScopePresentationHintLocals, |
333 | eScopePresentationHintRegisters, |
334 | eScopePresentationHintReturnValue |
335 | }; |
336 | /// Name of the scope such as 'Arguments', 'Locals', or 'Registers'. This |
337 | /// string is shown in the UI as is and can be translated. |
338 | //// |
339 | std::string name; |
340 | |
341 | /// A hint for how to present this scope in the UI. If this attribute is |
342 | /// missing, the scope is shown with a generic UI. |
343 | /// Values: |
344 | /// 'arguments': Scope contains method arguments. |
345 | /// 'locals': Scope contains local variables. |
346 | /// 'registers': Scope contains registers. Only a single `registers` scope |
347 | /// should be returned from a `scopes` request. |
348 | /// 'returnValue': Scope contains one or more return values. |
349 | /// etc. |
350 | std::optional<PresentationHint> presentationHint; |
351 | |
352 | /// The variables of this scope can be retrieved by passing the value of |
353 | /// `variablesReference` to the `variables` request as long as execution |
354 | /// remains suspended. See 'Lifetime of Object References' in the Overview |
355 | /// section for details. |
356 | //// |
357 | uint64_t variablesReference = LLDB_DAP_INVALID_VARRERF; |
358 | |
359 | /// The number of named variables in this scope. |
360 | /// The client can use this information to present the variables in a paged UI |
361 | /// and fetch them in chunks. |
362 | std::optional<uint64_t> namedVariables; |
363 | |
364 | /// The number of indexed variables in this scope. |
365 | /// The client can use this information to present the variables in a paged UI |
366 | /// and fetch them in chunks. |
367 | std::optional<uint64_t> indexedVariables; |
368 | |
369 | /// The source for this scope. |
370 | std::optional<Source> source; |
371 | |
372 | /// If true, the number of variables in this scope is large or expensive to |
373 | /// retrieve. |
374 | bool expensive = false; |
375 | |
376 | /// The start line of the range covered by this scope. |
377 | std::optional<uint64_t> line; |
378 | |
379 | /// Start position of the range covered by the scope. It is measured in UTF-16 |
380 | /// code units and the client capability `columnsStartAt1` determines whether |
381 | /// it is 0- or 1-based. |
382 | std::optional<uint64_t> column; |
383 | |
384 | /// The end line of the range covered by this scope. |
385 | std::optional<uint64_t> endLine; |
386 | |
387 | /// End position of the range covered by the scope. It is measured in UTF-16 |
388 | /// code units and the client capability `columnsStartAt1` determines whether |
389 | /// it is 0- or 1-based. |
390 | std::optional<uint64_t> endColumn; |
391 | }; |
392 | bool fromJSON(const llvm::json::Value &Params, Scope::PresentationHint &PH, |
393 | llvm::json::Path); |
394 | bool fromJSON(const llvm::json::Value &, Scope &, llvm::json::Path); |
395 | llvm::json::Value toJSON(const Scope &); |
396 | |
397 | /// The granularity of one `step` in the stepping requests `next`, `stepIn`, |
398 | /// `stepOut` and `stepBack`. |
399 | enum SteppingGranularity : unsigned { |
400 | /// The step should allow the program to run until the current statement has |
401 | /// finished executing. The meaning of a statement is determined by the |
402 | /// adapter and it may be considered equivalent to a line. For example |
403 | /// `for(int i = 0; i < 10; i++)` could be considered to have 3 statements |
404 | /// `int i = 0`, `i < 10`, and `i++`. |
405 | eSteppingGranularityStatement, |
406 | /// The step should allow the program to run until the current source line has |
407 | /// executed. |
408 | eSteppingGranularityLine, |
409 | /// The step should allow one instruction to execute (e.g. one x86 |
410 | /// instruction). |
411 | eSteppingGranularityInstruction, |
412 | }; |
413 | bool fromJSON(const llvm::json::Value &, SteppingGranularity &, |
414 | llvm::json::Path); |
415 | llvm::json::Value toJSON(const SteppingGranularity &); |
416 | |
417 | /// A Thread. |
418 | struct Thread { |
419 | /// Unique identifier for the thread. |
420 | lldb::tid_t id = LLDB_INVALID_THREAD_ID; |
421 | /// The name of the thread. |
422 | std::string name; |
423 | }; |
424 | bool fromJSON(const llvm::json::Value &, Thread &, llvm::json::Path); |
425 | llvm::json::Value toJSON(const Thread &); |
426 | |
427 | /// Provides formatting information for a value. |
428 | struct ValueFormat { |
429 | /// Display the value in hex. |
430 | std::optional<bool> hex; |
431 | }; |
432 | bool fromJSON(const llvm::json::Value &, ValueFormat &, llvm::json::Path); |
433 | |
434 | /// Properties of a breakpoint location returned from the `breakpointLocations` |
435 | /// request. |
436 | struct BreakpointLocation { |
437 | /// Start line of breakpoint location. |
438 | uint32_t line; |
439 | |
440 | /// The start position of a breakpoint location. Position is measured in |
441 | /// UTF-16 code units and the client capability `columnsStartAt1` determines |
442 | /// whether it is 0- or 1-based. |
443 | std::optional<uint32_t> column; |
444 | |
445 | /// The end line of breakpoint location if the location covers a range. |
446 | std::optional<uint32_t> endLine; |
447 | |
448 | /// The end position of a breakpoint location (if the location covers a |
449 | /// range). Position is measured in UTF-16 code units and the client |
450 | /// capability `columnsStartAt1` determines whether it is 0- or 1-based. |
451 | std::optional<uint32_t> endColumn; |
452 | }; |
453 | llvm::json::Value toJSON(const BreakpointLocation &); |
454 | |
455 | /// A machine-readable explanation of why a breakpoint may not be verified. |
456 | enum class BreakpointReason : unsigned { |
457 | /// Indicates a breakpoint might be verified in the future, but |
458 | /// the adapter cannot verify it in the current state. |
459 | eBreakpointReasonPending, |
460 | /// Indicates a breakpoint was not able to be verified, and the |
461 | /// adapter does not believe it can be verified without intervention. |
462 | eBreakpointReasonFailed, |
463 | }; |
464 | bool fromJSON(const llvm::json::Value &, BreakpointReason &, llvm::json::Path); |
465 | llvm::json::Value toJSON(const BreakpointReason &); |
466 | |
467 | /// Information about a breakpoint created in `setBreakpoints`, |
468 | /// `setFunctionBreakpoints`, `setInstructionBreakpoints`, or |
469 | /// `setDataBreakpoints` requests. |
470 | struct Breakpoint { |
471 | /// The identifier for the breakpoint. It is needed if breakpoint events are |
472 | /// used to update or remove breakpoints. |
473 | std::optional<int> id; |
474 | |
475 | /// If true, the breakpoint could be set (but not necessarily at the desired |
476 | /// location). |
477 | bool verified = false; |
478 | |
479 | /// A message about the state of the breakpoint. |
480 | /// This is shown to the user and can be used to explain why a breakpoint |
481 | /// could not be verified. |
482 | std::optional<std::string> message; |
483 | |
484 | /// The source where the breakpoint is located. |
485 | std::optional<Source> source; |
486 | |
487 | /// The start line of the actual range covered by the breakpoint. |
488 | std::optional<uint32_t> line; |
489 | |
490 | /// Start position of the source range covered by the breakpoint. It is |
491 | /// measured in UTF-16 code units and the client capability `columnsStartAt1` |
492 | /// determines whether it is 0- or 1-based. |
493 | std::optional<uint32_t> column; |
494 | |
495 | /// The end line of the actual range covered by the breakpoint. |
496 | std::optional<uint32_t> endLine; |
497 | |
498 | /// End position of the source range covered by the breakpoint. It is measured |
499 | /// in UTF-16 code units and the client capability `columnsStartAt1` |
500 | /// determines whether it is 0- or 1-based. If no end line is given, then the |
501 | /// end column is assumed to be in the start line. |
502 | std::optional<uint32_t> endColumn; |
503 | |
504 | /// A memory reference to where the breakpoint is set. |
505 | std::optional<std::string> instructionReference; |
506 | |
507 | /// The offset from the instruction reference. |
508 | /// This can be negative. |
509 | std::optional<int32_t> offset; |
510 | |
511 | /// A machine-readable explanation of why a breakpoint may not be verified. If |
512 | /// a breakpoint is verified or a specific reason is not known, the adapter |
513 | /// should omit this property. |
514 | std::optional<BreakpointReason> reason; |
515 | }; |
516 | bool fromJSON(const llvm::json::Value &, Breakpoint &, llvm::json::Path); |
517 | llvm::json::Value toJSON(const Breakpoint &); |
518 | |
519 | /// Properties of a breakpoint or logpoint passed to the `setBreakpoints` |
520 | /// request |
521 | struct SourceBreakpoint { |
522 | /// The source line of the breakpoint or logpoint. |
523 | uint32_t line = LLDB_INVALID_LINE_NUMBER; |
524 | |
525 | /// Start position within source line of the breakpoint or logpoint. It is |
526 | /// measured in UTF-16 code units and the client capability `columnsStartAt1` |
527 | /// determines whether it is 0- or 1-based. |
528 | std::optional<uint32_t> column; |
529 | |
530 | /// The expression for conditional breakpoints. |
531 | /// It is only honored by a debug adapter if the corresponding capability |
532 | /// `supportsConditionalBreakpoints` is true. |
533 | std::optional<std::string> condition; |
534 | |
535 | /// The expression that controls how many hits of the breakpoint are ignored. |
536 | /// The debug adapter is expected to interpret the expression as needed. |
537 | /// The attribute is only honored by a debug adapter if the corresponding |
538 | /// capability `supportsHitConditionalBreakpoints` is true. |
539 | /// If both this property and `condition` are specified, `hitCondition` should |
540 | /// be evaluated only if the `condition` is met, and the debug adapter should |
541 | /// stop only if both conditions are met. |
542 | std::optional<std::string> hitCondition; |
543 | |
544 | /// If this attribute exists and is non-empty, the debug adapter must not |
545 | /// 'break' (stop) |
546 | /// but log the message instead. Expressions within `{}` are interpolated. |
547 | /// The attribute is only honored by a debug adapter if the corresponding |
548 | /// capability `supportsLogPoints` is true. |
549 | /// If either `hitCondition` or `condition` is specified, then the message |
550 | /// should only be logged if those conditions are met. |
551 | std::optional<std::string> logMessage; |
552 | |
553 | /// The mode of this breakpoint. If defined, this must be one of the |
554 | /// `breakpointModes` the debug adapter advertised in its `Capabilities`. |
555 | std::optional<std::string> mode; |
556 | }; |
557 | bool fromJSON(const llvm::json::Value &, SourceBreakpoint &, llvm::json::Path); |
558 | llvm::json::Value toJSON(const SourceBreakpoint &); |
559 | |
560 | /// Properties of a breakpoint passed to the `setFunctionBreakpoints` request. |
561 | struct FunctionBreakpoint { |
562 | /// The name of the function. |
563 | std::string name; |
564 | |
565 | /// An expression for conditional breakpoints. |
566 | /// It is only honored by a debug adapter if the corresponding capability |
567 | /// `supportsConditionalBreakpoints` is true. |
568 | std::optional<std::string> condition; |
569 | |
570 | /// An expression that controls how many hits of the breakpoint are ignored. |
571 | /// The debug adapter is expected to interpret the expression as needed. |
572 | /// The attribute is only honored by a debug adapter if the corresponding |
573 | /// capability `supportsHitConditionalBreakpoints` is true. |
574 | std::optional<std::string> hitCondition; |
575 | }; |
576 | bool fromJSON(const llvm::json::Value &, FunctionBreakpoint &, |
577 | llvm::json::Path); |
578 | llvm::json::Value toJSON(const FunctionBreakpoint &); |
579 | |
580 | /// This enumeration defines all possible access types for data breakpoints. |
581 | /// Values: ‘read’, ‘write’, ‘readWrite’ |
582 | enum DataBreakpointAccessType : unsigned { |
583 | eDataBreakpointAccessTypeRead, |
584 | eDataBreakpointAccessTypeWrite, |
585 | eDataBreakpointAccessTypeReadWrite |
586 | }; |
587 | bool fromJSON(const llvm::json::Value &, DataBreakpointAccessType &, |
588 | llvm::json::Path); |
589 | llvm::json::Value toJSON(const DataBreakpointAccessType &); |
590 | |
591 | /// Properties of a data breakpoint passed to the `setDataBreakpoints` request. |
592 | struct DataBreakpoint { |
593 | /// An id representing the data. This id is returned from the |
594 | /// `dataBreakpointInfo` request. |
595 | std::string dataId; |
596 | |
597 | /// The access type of the data. |
598 | std::optional<DataBreakpointAccessType> accessType; |
599 | |
600 | /// An expression for conditional breakpoints. |
601 | std::optional<std::string> condition; |
602 | |
603 | /// An expression that controls how many hits of the breakpoint are ignored. |
604 | /// The debug adapter is expected to interpret the expression as needed. |
605 | std::optional<std::string> hitCondition; |
606 | }; |
607 | bool fromJSON(const llvm::json::Value &, DataBreakpoint &, llvm::json::Path); |
608 | llvm::json::Value toJSON(const DataBreakpoint &); |
609 | |
610 | /// Properties of a breakpoint passed to the `setInstructionBreakpoints` request |
611 | struct InstructionBreakpoint { |
612 | /// The instruction reference of the breakpoint. |
613 | /// This should be a memory or instruction pointer reference from an |
614 | /// `EvaluateResponse`, `Variable`, `StackFrame`, `GotoTarget`, or |
615 | /// `Breakpoint`. |
616 | std::string instructionReference; |
617 | |
618 | /// The offset from the instruction reference in bytes. |
619 | /// This can be negative. |
620 | std::optional<int32_t> offset; |
621 | |
622 | /// An expression for conditional breakpoints. |
623 | /// It is only honored by a debug adapter if the corresponding capability |
624 | /// `supportsConditionalBreakpoints` is true. |
625 | std::optional<std::string> condition; |
626 | |
627 | /// An expression that controls how many hits of the breakpoint are ignored. |
628 | /// The debug adapter is expected to interpret the expression as needed. |
629 | /// The attribute is only honored by a debug adapter if the corresponding |
630 | /// capability `supportsHitConditionalBreakpoints` is true. |
631 | std::optional<std::string> hitCondition; |
632 | |
633 | /// The mode of this breakpoint. If defined, this must be one of the |
634 | /// `breakpointModes` the debug adapter advertised in its `Capabilities`. |
635 | std::optional<std::string> mode; |
636 | }; |
637 | bool fromJSON(const llvm::json::Value &, InstructionBreakpoint &, |
638 | llvm::json::Path); |
639 | |
640 | /// Properties of a single disassembled instruction, returned by `disassemble` |
641 | /// request. |
642 | struct DisassembledInstruction { |
643 | enum PresentationHint : unsigned { |
644 | eDisassembledInstructionPresentationHintNormal, |
645 | eDisassembledInstructionPresentationHintInvalid, |
646 | }; |
647 | |
648 | /// The address of the instruction. Treated as a hex value if prefixed with |
649 | /// `0x`, or as a decimal value otherwise. |
650 | lldb::addr_t address = LLDB_INVALID_ADDRESS; |
651 | |
652 | /// Raw bytes representing the instruction and its operands, in an |
653 | /// implementation-defined format. |
654 | std::optional<std::string> instructionBytes; |
655 | |
656 | /// Text representing the instruction and its operands, in an |
657 | /// implementation-defined format. |
658 | std::string instruction; |
659 | |
660 | /// Name of the symbol that corresponds with the location of this instruction, |
661 | /// if any. |
662 | std::optional<std::string> symbol; |
663 | |
664 | /// Source location that corresponds to this instruction, if any. |
665 | /// Should always be set (if available) on the first instruction returned, |
666 | /// but can be omitted afterwards if this instruction maps to the same source |
667 | /// file as the previous instruction. |
668 | std::optional<protocol::Source> location; |
669 | |
670 | /// The line within the source location that corresponds to this instruction, |
671 | /// if any. |
672 | std::optional<uint32_t> line; |
673 | |
674 | /// The column within the line that corresponds to this instruction, if any. |
675 | std::optional<uint32_t> column; |
676 | |
677 | /// The end line of the range that corresponds to this instruction, if any. |
678 | std::optional<uint32_t> endLine; |
679 | |
680 | /// The end column of the range that corresponds to this instruction, if any. |
681 | std::optional<uint32_t> endColumn; |
682 | |
683 | /// A hint for how to present the instruction in the UI. |
684 | /// |
685 | /// A value of `invalid` may be used to indicate this instruction is 'filler' |
686 | /// and cannot be reached by the program. For example, unreadable memory |
687 | /// addresses may be presented is 'invalid.' |
688 | /// Values: 'normal', 'invalid' |
689 | std::optional<PresentationHint> presentationHint; |
690 | }; |
691 | bool fromJSON(const llvm::json::Value &, |
692 | DisassembledInstruction::PresentationHint &, llvm::json::Path); |
693 | llvm::json::Value toJSON(const DisassembledInstruction::PresentationHint &); |
694 | bool fromJSON(const llvm::json::Value &, DisassembledInstruction &, |
695 | llvm::json::Path); |
696 | llvm::json::Value toJSON(const DisassembledInstruction &); |
697 | |
698 | } // namespace lldb_dap::protocol |
699 | |
700 | #endif |
701 | |