1 | //===-- LLDBUtils.h ---------------------------------------------*- C++ -*-===// |
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 | #ifndef LLDB_TOOLS_LLDB_DAP_LLDBUTILS_H |
10 | #define LLDB_TOOLS_LLDB_DAP_LLDBUTILS_H |
11 | |
12 | #include "DAPForward.h" |
13 | #include "lldb/API/SBDebugger.h" |
14 | #include "lldb/API/SBEnvironment.h" |
15 | #include "lldb/API/SBError.h" |
16 | #include "lldb/API/SBFileSpec.h" |
17 | #include "lldb/API/SBLineEntry.h" |
18 | #include "lldb/API/SBTarget.h" |
19 | #include "llvm/ADT/ArrayRef.h" |
20 | #include "llvm/ADT/StringRef.h" |
21 | #include "llvm/Support/Error.h" |
22 | #include "llvm/Support/JSON.h" |
23 | #include "llvm/Support/ScopedPrinter.h" |
24 | #include "llvm/Support/raw_ostream.h" |
25 | #include <chrono> |
26 | #include <string> |
27 | |
28 | namespace lldb_dap { |
29 | |
30 | /// Run a list of LLDB commands in the LLDB command interpreter. |
31 | /// |
32 | /// All output from every command, including the prompt + the command |
33 | /// is placed into the "strm" argument. |
34 | /// |
35 | /// Each individual command can be prefixed with \b ! and/or \b ? in no |
36 | /// particular order. If \b ? is provided, then the output of that command is |
37 | /// only emitted if it fails, and if \b ! is provided, then the output is |
38 | /// emitted regardless, and \b false is returned without executing the |
39 | /// remaining commands. |
40 | /// |
41 | /// \param[in] debugger |
42 | /// The debugger that will execute the lldb commands. |
43 | /// |
44 | /// \param[in] prefix |
45 | /// A string that will be printed into \a strm prior to emitting |
46 | /// the prompt + command and command output. Can be NULL. |
47 | /// |
48 | /// \param[in] commands |
49 | /// An array of LLDB commands to execute. |
50 | /// |
51 | /// \param[in] strm |
52 | /// The stream that will receive the prefix, prompt + command and |
53 | /// all command output. |
54 | /// |
55 | /// \param[in] parse_command_directives |
56 | /// If \b false, then command prefixes like \b ! or \b ? are not parsed and |
57 | /// each command is executed verbatim. |
58 | /// |
59 | /// \param[in] echo_commands |
60 | /// If \b true, the command are echoed to the stream. |
61 | /// |
62 | /// \return |
63 | /// \b true, unless a command prefixed with \b ! fails and parsing of |
64 | /// command directives is enabled. |
65 | bool RunLLDBCommands(lldb::SBDebugger &debugger, llvm::StringRef prefix, |
66 | const llvm::ArrayRef<std::string> &commands, |
67 | llvm::raw_ostream &strm, bool parse_command_directives, |
68 | bool echo_commands); |
69 | |
70 | /// Run a list of LLDB commands in the LLDB command interpreter. |
71 | /// |
72 | /// All output from every command, including the prompt + the command |
73 | /// is returned in the std::string return value. |
74 | /// |
75 | /// \param[in] debugger |
76 | /// The debugger that will execute the lldb commands. |
77 | /// |
78 | /// \param[in] prefix |
79 | /// A string that will be printed into \a strm prior to emitting |
80 | /// the prompt + command and command output. Can be NULL. |
81 | /// |
82 | /// \param[in] commands |
83 | /// An array of LLDB commands to execute. |
84 | /// |
85 | /// \param[out] required_command_failed |
86 | /// If parsing of command directives is enabled, this variable is set to |
87 | /// \b true if one of the commands prefixed with \b ! fails. |
88 | /// |
89 | /// \param[in] parse_command_directives |
90 | /// If \b false, then command prefixes like \b ! or \b ? are not parsed and |
91 | /// each command is executed verbatim. |
92 | /// |
93 | /// \param[in] echo_commands |
94 | /// If \b true, the command are echoed to the stream. |
95 | /// |
96 | /// \return |
97 | /// A std::string that contains the prefix and all commands and |
98 | /// command output. |
99 | std::string RunLLDBCommands(lldb::SBDebugger &debugger, llvm::StringRef prefix, |
100 | const llvm::ArrayRef<std::string> &commands, |
101 | bool &required_command_failed, |
102 | bool parse_command_directives = true, |
103 | bool echo_commands = false); |
104 | |
105 | /// Check if a thread has a stop reason. |
106 | /// |
107 | /// \param[in] thread |
108 | /// The LLDB thread object to check |
109 | /// |
110 | /// \return |
111 | /// \b True if the thread has a valid stop reason, \b false |
112 | /// otherwise. |
113 | bool ThreadHasStopReason(lldb::SBThread &thread); |
114 | |
115 | /// Given a LLDB frame, make a frame ID that is unique to a specific |
116 | /// thread and frame. |
117 | /// |
118 | /// DAP requires a Stackframe "id" to be unique, so we use the frame |
119 | /// index in the lower 32 bits and the thread index ID in the upper 32 |
120 | /// bits. |
121 | /// |
122 | /// \param[in] frame |
123 | /// The LLDB stack frame object generate the ID for |
124 | /// |
125 | /// \return |
126 | /// A unique integer that allows us to easily find the right |
127 | /// stack frame within a thread on subsequent VS code requests. |
128 | int64_t MakeDAPFrameID(lldb::SBFrame &frame); |
129 | |
130 | /// Given a DAP frame ID, convert to a LLDB thread index id. |
131 | /// |
132 | /// DAP requires a Stackframe "id" to be unique, so we use the frame |
133 | /// index in the lower THREAD_INDEX_SHIFT bits and the thread index ID in |
134 | /// the upper 32 - THREAD_INDEX_SHIFT bits. |
135 | /// |
136 | /// \param[in] dap_frame_id |
137 | /// The DAP frame ID to convert to a thread index ID. |
138 | /// |
139 | /// \return |
140 | /// The LLDB thread index ID. |
141 | uint32_t GetLLDBThreadIndexID(uint64_t dap_frame_id); |
142 | |
143 | /// Given a DAP frame ID, convert to a LLDB frame ID. |
144 | /// |
145 | /// DAP requires a Stackframe "id" to be unique, so we use the frame |
146 | /// index in the lower THREAD_INDEX_SHIFT bits and the thread index ID in |
147 | /// the upper 32 - THREAD_INDEX_SHIFT bits. |
148 | /// |
149 | /// \param[in] dap_frame_id |
150 | /// The DAP frame ID to convert to a frame ID. |
151 | /// |
152 | /// \return |
153 | /// The LLDB frame index ID. |
154 | uint32_t GetLLDBFrameID(uint64_t dap_frame_id); |
155 | |
156 | /// Gets all the environment variables from the json object depending on if the |
157 | /// kind is an object or an array. |
158 | /// |
159 | /// \param[in] arguments |
160 | /// The json object with the launch options |
161 | /// |
162 | /// \return |
163 | /// The environment variables stored in the env key |
164 | lldb::SBEnvironment |
165 | GetEnvironmentFromArguments(const llvm::json::Object &arguments); |
166 | |
167 | /// Gets an SBFileSpec and returns its path as a string. |
168 | /// |
169 | /// \param[in] file_spec |
170 | /// The file spec. |
171 | /// |
172 | /// \return |
173 | /// The file path as a string. |
174 | std::string GetSBFileSpecPath(const lldb::SBFileSpec &file_spec); |
175 | |
176 | /// Gets the line entry for a given address. |
177 | /// \param[in] target |
178 | /// The target that has the address. |
179 | /// |
180 | /// \param[in] address |
181 | /// The address for which to get the line entry. |
182 | /// |
183 | /// \return |
184 | /// The line entry for the given address. |
185 | lldb::SBLineEntry GetLineEntryForAddress(lldb::SBTarget &target, |
186 | const lldb::SBAddress &address); |
187 | |
188 | /// Helper for sending telemetry to lldb server, if client-telemetry is enabled. |
189 | class TelemetryDispatcher { |
190 | public: |
191 | TelemetryDispatcher(lldb::SBDebugger *debugger) { |
192 | m_telemetry_json = llvm::json::Object(); |
193 | m_telemetry_json.try_emplace( |
194 | K: "start_time" , |
195 | Args: std::chrono::steady_clock::now().time_since_epoch().count()); |
196 | this->debugger = debugger; |
197 | } |
198 | |
199 | void Set(std::string key, std::string value) { |
200 | m_telemetry_json.try_emplace(K: key, Args&: value); |
201 | } |
202 | |
203 | void Set(std::string key, int64_t value) { |
204 | m_telemetry_json.try_emplace(K: key, Args&: value); |
205 | } |
206 | |
207 | ~TelemetryDispatcher() { |
208 | m_telemetry_json.try_emplace( |
209 | K: "end_time" , |
210 | Args: std::chrono::steady_clock::now().time_since_epoch().count()); |
211 | |
212 | lldb::SBStructuredData telemetry_entry; |
213 | llvm::json::Value val(std::move(m_telemetry_json)); |
214 | |
215 | std::string string_rep = llvm::to_string(Value: val); |
216 | telemetry_entry.SetFromJSON(string_rep.c_str()); |
217 | debugger->DispatchClientTelemetry(data: telemetry_entry); |
218 | } |
219 | |
220 | private: |
221 | llvm::json::Object m_telemetry_json; |
222 | lldb::SBDebugger *debugger; |
223 | }; |
224 | |
225 | /// RAII utility to put the debugger temporarily into synchronous mode. |
226 | class ScopeSyncMode { |
227 | public: |
228 | ScopeSyncMode(lldb::SBDebugger &debugger); |
229 | ~ScopeSyncMode(); |
230 | |
231 | private: |
232 | lldb::SBDebugger &m_debugger; |
233 | bool m_async; |
234 | }; |
235 | |
236 | /// Get the stop-disassembly-display settings |
237 | /// |
238 | /// \param[in] debugger |
239 | /// The debugger that will execute the lldb commands. |
240 | /// |
241 | /// \return |
242 | /// The value of the stop-disassembly-display setting |
243 | lldb::StopDisassemblyType GetStopDisassemblyDisplay(lldb::SBDebugger &debugger); |
244 | |
245 | /// Take ownership of the stored error. |
246 | llvm::Error ToError(const lldb::SBError &error); |
247 | |
248 | /// Provides the string value if this data structure is a string type. |
249 | std::string GetStringValue(const lldb::SBStructuredData &data); |
250 | |
251 | } // namespace lldb_dap |
252 | |
253 | #endif |
254 | |