1//===-- ProtocolUtils.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 Utility function for protocol objects.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_UTILS_H
14#define LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_UTILS_H
15
16#include "ExceptionBreakpoint.h"
17#include "Protocol/ProtocolTypes.h"
18
19#include "lldb/API/SBAddress.h"
20
21namespace lldb_dap {
22
23/// Converts a LLDB module to a DAP protocol module for use in `module events or
24/// request.
25///
26/// \param[in] target
27/// The target that has the module
28///
29/// \param[in] module
30/// A LLDB module object to convert into a protocol module
31///
32/// \param[in] id_only
33/// Only initialize the module ID in the return type. This is used when
34/// sending a "removed" module event.
35///
36/// \return
37/// A `protocol::Module` that follows the formal Module
38/// definition outlined by the DAP protocol.
39std::optional<protocol::Module> CreateModule(const lldb::SBTarget &target,
40 lldb::SBModule &module,
41 bool id_only = false);
42
43/// Create a "Source" JSON object as described in the debug adapter definition.
44///
45/// \param[in] file
46/// The SBFileSpec to use when populating out the "Source" object
47///
48/// \return
49/// An optional "Source" JSON object that follows the formal JSON
50/// definition outlined by Microsoft.
51std::optional<protocol::Source> CreateSource(const lldb::SBFileSpec &file);
52
53/// Checks if the given source is for assembly code.
54bool IsAssemblySource(const protocol::Source &source);
55
56bool DisplayAssemblySource(lldb::SBDebugger &debugger, lldb::SBAddress address);
57
58/// Get the address as a 16-digit hex string, e.g. "0x0000000000012345"
59std::string GetLoadAddressString(const lldb::addr_t addr);
60
61/// Create a "Thread" object for a LLDB thread object.
62///
63/// This function will fill in the following keys in the returned
64/// object:
65/// "id" - the thread ID as an integer
66/// "name" - the thread name as a string which combines the LLDB
67/// thread index ID along with the string name of the thread
68/// from the OS if it has a name.
69///
70/// \param[in] thread
71/// The LLDB thread to use when populating out the "Thread"
72/// object.
73///
74/// \param[in] format
75/// The LLDB format to use when populating out the "Thread"
76/// object.
77///
78/// \return
79/// A "Thread" JSON object with that follows the formal JSON
80/// definition outlined by Microsoft.
81protocol::Thread CreateThread(lldb::SBThread &thread, lldb::SBFormat &format);
82
83/// Returns the set of threads associated with the process.
84std::vector<protocol::Thread> GetThreads(lldb::SBProcess process,
85 lldb::SBFormat &format);
86
87/// Create a "ExceptionBreakpointsFilter" JSON object as described in
88/// the debug adapter definition.
89///
90/// \param[in] bp
91/// The exception breakpoint object to use
92///
93/// \return
94/// A "ExceptionBreakpointsFilter" JSON object with that follows
95/// the formal JSON definition outlined by Microsoft.
96protocol::ExceptionBreakpointsFilter
97CreateExceptionBreakpointFilter(const ExceptionBreakpoint &bp);
98
99/// Converts a size in bytes to a human-readable string format.
100///
101/// \param[in] debug_size
102/// Size of the debug information in bytes (uint64_t).
103///
104/// \return
105/// A string representing the size in a readable format (e.g., "1 KB",
106/// "2 MB").
107std::string ConvertDebugInfoSizeToString(uint64_t debug_size);
108
109/// Create a protocol Variable for the given value.
110///
111/// \param[in] v
112/// The LLDB value to use when populating out the "Variable"
113/// object.
114///
115/// \param[in] var_ref
116/// The variable reference. Used to identify the value, e.g.
117/// in the `variablesReference` or `declarationLocationReference`
118/// properties.
119///
120/// \param[in] format_hex
121/// If set to true the variable will be formatted as hex in
122/// the "value" key value pair for the value of the variable.
123///
124/// \param[in] auto_variable_summaries
125/// If set to true the variable will create an automatic variable summary.
126///
127/// \param[in] synthetic_child_debugging
128/// Whether to include synthetic children when listing properties of the
129/// value.
130///
131/// \param[in] is_name_duplicated
132/// Whether the same variable name appears multiple times within the same
133/// context (e.g. locals). This can happen due to shadowed variables in
134/// nested blocks.
135///
136/// As VSCode doesn't render two of more variables with the same name, we
137/// apply a suffix to distinguish duplicated variables.
138///
139/// \param[in] custom_name
140/// A provided custom name that is used instead of the SBValue's when
141/// creating the JSON representation.
142///
143/// \return
144/// A Variable representing the given value.
145protocol::Variable CreateVariable(lldb::SBValue v, int64_t var_ref,
146 bool format_hex, bool auto_variable_summaries,
147 bool synthetic_child_debugging,
148 bool is_name_duplicated,
149 std::optional<std::string> custom_name = {});
150
151} // namespace lldb_dap
152
153#endif
154

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