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 "llvm/ADT/ArrayRef.h"
14#include "llvm/ADT/StringRef.h"
15#include "llvm/Support/raw_ostream.h"
16#include <string>
17#include <vector>
18
19namespace lldb_dap {
20
21/// Run a list of LLDB commands in the LLDB command interpreter.
22///
23/// All output from every command, including the prompt + the command
24/// is placed into the "strm" argument.
25///
26/// Each individual command can be prefixed with \b ! and/or \b ? in no
27/// particular order. If \b ? is provided, then the output of that command is
28/// only emitted if it fails, and if \b ! is provided, then the output is
29/// emitted regardless, and \b false is returned without executing the
30/// remaining commands.
31///
32/// \param[in] prefix
33/// A string that will be printed into \a strm prior to emitting
34/// the prompt + command and command output. Can be NULL.
35///
36/// \param[in] commands
37/// An array of LLDB commands to execute.
38///
39/// \param[in] strm
40/// The stream that will receive the prefix, prompt + command and
41/// all command output.
42///
43/// \param[in] parse_command_directives
44/// If \b false, then command prefixes like \b ! or \b ? are not parsed and
45/// each command is executed verbatim.
46///
47/// \return
48/// \b true, unless a command prefixed with \b ! fails and parsing of
49/// command directives is enabled.
50bool RunLLDBCommands(llvm::StringRef prefix,
51 const llvm::ArrayRef<std::string> &commands,
52 llvm::raw_ostream &strm, bool parse_command_directives);
53
54/// Run a list of LLDB commands in the LLDB command interpreter.
55///
56/// All output from every command, including the prompt + the command
57/// is returned in the std::string return value.
58///
59/// \param[in] prefix
60/// A string that will be printed into \a strm prior to emitting
61/// the prompt + command and command output. Can be NULL.
62///
63/// \param[in] commands
64/// An array of LLDB commands to execute.
65///
66/// \param[out] required_command_failed
67/// If parsing of command directives is enabled, this variable is set to
68/// \b true if one of the commands prefixed with \b ! fails.
69///
70/// \param[in] parse_command_directives
71/// If \b false, then command prefixes like \b ! or \b ? are not parsed and
72/// each command is executed verbatim.
73///
74/// \return
75/// A std::string that contains the prefix and all commands and
76/// command output.
77std::string RunLLDBCommands(llvm::StringRef prefix,
78 const llvm::ArrayRef<std::string> &commands,
79 bool &required_command_failed,
80 bool parse_command_directives = true);
81
82/// Similar to the method above, but without parsing command directives.
83std::string
84RunLLDBCommandsVerbatim(llvm::StringRef prefix,
85 const llvm::ArrayRef<std::string> &commands);
86
87/// Check if a thread has a stop reason.
88///
89/// \param[in] thread
90/// The LLDB thread object to check
91///
92/// \return
93/// \b True if the thread has a valid stop reason, \b false
94/// otherwise.
95bool ThreadHasStopReason(lldb::SBThread &thread);
96
97/// Given a LLDB frame, make a frame ID that is unique to a specific
98/// thread and frame.
99///
100/// DAP requires a Stackframe "id" to be unique, so we use the frame
101/// index in the lower 32 bits and the thread index ID in the upper 32
102/// bits.
103///
104/// \param[in] frame
105/// The LLDB stack frame object generate the ID for
106///
107/// \return
108/// A unique integer that allows us to easily find the right
109/// stack frame within a thread on subsequent VS code requests.
110int64_t MakeDAPFrameID(lldb::SBFrame &frame);
111
112/// Given a DAP frame ID, convert to a LLDB thread index id.
113///
114/// DAP requires a Stackframe "id" to be unique, so we use the frame
115/// index in the lower THREAD_INDEX_SHIFT bits and the thread index ID in
116/// the upper 32 - THREAD_INDEX_SHIFT bits.
117///
118/// \param[in] dap_frame_id
119/// The DAP frame ID to convert to a thread index ID.
120///
121/// \return
122/// The LLDB thread index ID.
123uint32_t GetLLDBThreadIndexID(uint64_t dap_frame_id);
124
125/// Given a DAP frame ID, convert to a LLDB frame ID.
126///
127/// DAP requires a Stackframe "id" to be unique, so we use the frame
128/// index in the lower THREAD_INDEX_SHIFT bits and the thread index ID in
129/// the upper 32 - THREAD_INDEX_SHIFT bits.
130///
131/// \param[in] dap_frame_id
132/// The DAP frame ID to convert to a frame ID.
133///
134/// \return
135/// The LLDB frame index ID.
136uint32_t GetLLDBFrameID(uint64_t dap_frame_id);
137
138} // namespace lldb_dap
139
140#endif
141

source code of lldb/tools/lldb-dap/LLDBUtils.h