155 lines · c
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-exception6//7//===----------------------------------------------------------------------===//8//9// This file contains Utility function for protocol objects.10//11//===----------------------------------------------------------------------===//12 13#ifndef LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_UTILS_H14#define LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_UTILS_H15 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 or24/// request.25///26/// \param[in] target27/// The target that has the module28///29/// \param[in] module30/// A LLDB module object to convert into a protocol module31///32/// \param[in] id_only33/// Only initialize the module ID in the return type. This is used when34/// sending a "removed" module event.35///36/// \return37/// A `protocol::Module` that follows the formal Module38/// 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] file46/// The SBFileSpec to use when populating out the "Source" object47///48/// \return49/// An optional "Source" JSON object that follows the formal JSON50/// 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,57 lldb::SBLineEntry line_entry);58 59/// Get the address as a 16-digit hex string, e.g. "0x0000000000012345"60std::string GetLoadAddressString(const lldb::addr_t addr);61 62/// Create a "Thread" object for a LLDB thread object.63///64/// This function will fill in the following keys in the returned65/// object:66/// "id" - the thread ID as an integer67/// "name" - the thread name as a string which combines the LLDB68/// thread index ID along with the string name of the thread69/// from the OS if it has a name.70///71/// \param[in] thread72/// The LLDB thread to use when populating out the "Thread"73/// object.74///75/// \param[in] format76/// The LLDB format to use when populating out the "Thread"77/// object.78///79/// \return80/// A "Thread" JSON object with that follows the formal JSON81/// definition outlined by Microsoft.82protocol::Thread CreateThread(lldb::SBThread &thread, lldb::SBFormat &format);83 84/// Returns the set of threads associated with the process.85std::vector<protocol::Thread> GetThreads(lldb::SBProcess process,86 lldb::SBFormat &format);87 88/// Create a "ExceptionBreakpointsFilter" JSON object as described in89/// the debug adapter definition.90///91/// \param[in] bp92/// The exception breakpoint object to use93///94/// \return95/// A "ExceptionBreakpointsFilter" JSON object with that follows96/// the formal JSON definition outlined by Microsoft.97protocol::ExceptionBreakpointsFilter98CreateExceptionBreakpointFilter(const ExceptionBreakpoint &bp);99 100/// Converts a size in bytes to a human-readable string format.101///102/// \param[in] debug_size103/// Size of the debug information in bytes (uint64_t).104///105/// \return106/// A string representing the size in a readable format (e.g., "1 KB",107/// "2 MB").108std::string ConvertDebugInfoSizeToString(uint64_t debug_size);109 110/// Create a protocol Variable for the given value.111///112/// \param[in] v113/// The LLDB value to use when populating out the "Variable"114/// object.115///116/// \param[in] var_ref117/// The variable reference. Used to identify the value, e.g.118/// in the `variablesReference` or `declarationLocationReference`119/// properties.120///121/// \param[in] format_hex122/// If set to true the variable will be formatted as hex in123/// the "value" key value pair for the value of the variable.124///125/// \param[in] auto_variable_summaries126/// If set to true the variable will create an automatic variable summary.127///128/// \param[in] synthetic_child_debugging129/// Whether to include synthetic children when listing properties of the130/// value.131///132/// \param[in] is_name_duplicated133/// Whether the same variable name appears multiple times within the same134/// context (e.g. locals). This can happen due to shadowed variables in135/// nested blocks.136///137/// As VSCode doesn't render two of more variables with the same name, we138/// apply a suffix to distinguish duplicated variables.139///140/// \param[in] custom_name141/// A provided custom name that is used instead of the SBValue's when142/// creating the JSON representation.143///144/// \return145/// A Variable representing the given value.146protocol::Variable CreateVariable(lldb::SBValue v, int64_t var_ref,147 bool format_hex, bool auto_variable_summaries,148 bool synthetic_child_debugging,149 bool is_name_duplicated,150 std::optional<std::string> custom_name = {});151 152} // namespace lldb_dap153 154#endif155