TheRock/compiler/amd-llvm/lldb/tools/lldb-dap/ProtocolUtils.h

//===-- ProtocolUtils.h ---------------------------------------------------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// This file contains Utility function for protocol objects.
//
//===----------------------------------------------------------------------===//

#ifndef LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_UTILS_H
#define LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_UTILS_H

#include "ExceptionBreakpoint.h"
#include "Protocol/ProtocolTypes.h"

#include "lldb/API/SBAddress.h"
#include "lldb/lldb-types.h"

namespace lldb_dap {

/// Converts a LLDB module to a DAP protocol module for use in `module events or
/// request.
///
/// \param[in] target
///     The target that has the module
///
/// \param[in] module
///     A LLDB module object to convert into a protocol module
///
/// \param[in] id_only
///     Only initialize the module ID in the return type. This is used when
///     sending a "removed" module event.
///
/// \return
///     A `protocol::Module` that follows the formal Module
///     definition outlined by the DAP protocol.
std::optional<protocol::Module> CreateModule(const lldb::SBTarget &target,
                                             lldb::SBModule &module,
                                             bool id_only = false);

/// Create a "Source" JSON object as described in the debug adapter definition.
///
/// \param[in] file
///     The SBFileSpec to use when populating out the "Source" object
///
/// \return
///     An optional "Source" JSON object that follows the formal JSON
///     definition outlined by Microsoft.
std::optional<protocol::Source> CreateSource(const lldb::SBFileSpec &file);

/// Checks if the given source is for assembly code.
bool IsAssemblySource(const protocol::Source &source);

bool DisplayAssemblySource(lldb::SBDebugger &debugger,
                           lldb::SBLineEntry line_entry);

/// Get the address as a 16-digit hex string, e.g. "0x0000000000012345"
std::string GetLoadAddressString(const lldb::addr_t addr);

/// Create a "Thread" object for a LLDB thread object.
///
/// This function will fill in the following keys in the returned
/// object:
///   "id" - the thread ID as an integer
///   "name" - the thread name as a string which combines the LLDB
///            thread index ID along with the string name of the thread
///            from the OS if it has a name.
///
/// \param[in] thread
///     The LLDB thread to use when populating out the "Thread"
///     object.
///
/// \param[in] format
///     The LLDB format to use when populating out the "Thread"
///     object.
///
/// \return
///     A "Thread" JSON object with that follows the formal JSON
///     definition outlined by Microsoft.
protocol::Thread CreateThread(lldb::SBThread &thread, lldb::SBFormat &format);

/// Returns the set of threads associated with the process.
std::vector<protocol::Thread> GetThreads(lldb::SBProcess process,
                                         lldb::SBFormat &format);

/// Create a "ExceptionBreakpointsFilter" JSON object as described in
/// the debug adapter definition.
///
/// \param[in] bp
///     The exception breakpoint object to use
///
/// \return
///     A "ExceptionBreakpointsFilter" JSON object with that follows
///     the formal JSON definition outlined by Microsoft.
protocol::ExceptionBreakpointsFilter
CreateExceptionBreakpointFilter(const ExceptionBreakpoint &bp);

/// Converts a size in bytes to a human-readable string format.
///
/// \param[in] debug_size
///     Size of the debug information in bytes (uint64_t).
///
/// \return
///     A string representing the size in a readable format (e.g., "1 KB",
///     "2 MB").
std::string ConvertDebugInfoSizeToString(uint64_t debug_size);

/// Add a mask to the breakpoint's id, this is to avoid id collision
/// as internally, lldb breakpoint's id and watchpoint's id starts from one.
/// Similar to the variables_reference we start from 8'000'000.
inline lldb::break_id_t ApplyWatchpointMask(lldb::break_id_t breakpoint_id) {
  constexpr lldb::break_id_t watchpoint_mask = 8'000'000;
  return watchpoint_mask + breakpoint_id;
}

} // namespace lldb_dap

#endif