TheRock/compiler/amd-llvm/lldb/tools/lldb-dap/Protocol/ProtocolEvents.h

//===-- ProtocolEvents.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 POD structs based on the DAP specification at
// https://microsoft.github.io/debug-adapter-protocol/specification
//
// This is not meant to be a complete implementation, new interfaces are added
// when they're needed.
//
// Each struct has a toJSON and fromJSON function, that converts between
// the struct and a JSON representation. (See JSON.h)
//
//===----------------------------------------------------------------------===//

#ifndef LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_EVENTS_H
#define LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_EVENTS_H

#include "Protocol/ProtocolTypes.h"
#include "lldb/lldb-defines.h"
#include "lldb/lldb-types.h"
#include "llvm/Support/JSON.h"
#include <cstdint>
#include <optional>
#include <vector>

namespace lldb_dap::protocol {

/// The event indicates that one or more capabilities have changed.
///
/// Since the capabilities are dependent on the client and its UI, it might not
/// be possible to change that at random times (or too late).
///
/// Consequently this event has a hint characteristic: a client can only be
/// expected to make a 'best effort' in honoring individual capabilities but
/// there are no guarantees.
///
/// Only changed capabilities need to be included, all other capabilities keep
/// their values.
struct CapabilitiesEventBody {
  Capabilities capabilities;
};
llvm::json::Value toJSON(const CapabilitiesEventBody &);

/// The event indicates that some information about a module has changed.
struct ModuleEventBody {
  enum Reason : unsigned { eReasonNew, eReasonChanged, eReasonRemoved };

  /// The new, changed, or removed module. In case of `removed` only the module
  /// id is used.
  Module module;

  /// The reason for the event.
  /// Values: 'new', 'changed', 'removed'
  Reason reason;
};
llvm::json::Value toJSON(const ModuleEventBody::Reason &);
llvm::json::Value toJSON(const ModuleEventBody &);

/// This event signals that some state in the debug adapter has changed and
/// requires that the client needs to re-render the data snapshot previously
/// requested.
///
/// Debug adapters do not have to emit this event for runtime changes like
/// stopped or thread events because in that case the client refetches the new
/// state anyway. But the event can be used for example to refresh the UI after
/// rendering formatting has changed in the debug adapter.
///
/// This event should only be sent if the corresponding capability
/// supportsInvalidatedEvent is true.
struct InvalidatedEventBody {
  enum Area : unsigned { eAreaAll, eAreaStacks, eAreaThreads, eAreaVariables };

  /// Set of logical areas that got invalidated.
  std::vector<Area> areas;

  /// If specified, the client only needs to refetch data related to this
  /// thread.
  std::optional<lldb::tid_t> threadId;

  /// If specified, the client only needs to refetch data related to this stack
  /// frame (and the `threadId` is ignored).
  std::optional<uint64_t> stackFrameId;
};
llvm::json::Value toJSON(const InvalidatedEventBody::Area &);
llvm::json::Value toJSON(const InvalidatedEventBody &);

/// This event indicates that some memory range has been updated. It should only
/// be sent if the corresponding capability supportsMemoryEvent is true.
///
/// Clients typically react to the event by re-issuing a readMemory request if
/// they show the memory identified by the memoryReference and if the updated
/// memory range overlaps the displayed range. Clients should not make
/// assumptions how individual memory references relate to each other, so they
/// should not assume that they are part of a single continuous address range
/// and might overlap.
///
/// Debug adapters can use this event to indicate that the contents of a memory
/// range has changed due to some other request like setVariable or
/// setExpression. Debug adapters are not expected to emit this event for each
/// and every memory change of a running program, because that information is
/// typically not available from debuggers and it would flood clients with too
/// many events.
struct MemoryEventBody {
  /// Memory reference of a memory range that has been updated.
  lldb::addr_t memoryReference = LLDB_INVALID_ADDRESS;

  /// Starting offset in bytes where memory has been updated. Can be negative.
  int64_t offset = 0;

  /// Number of bytes updated.
  uint64_t count = 0;
};
llvm::json::Value toJSON(const MemoryEventBody &);

enum StoppedReason : unsigned {
  eStoppedReasonUninitialized,
  eStoppedReasonStep,
  eStoppedReasonBreakpoint,
  eStoppedReasonException,
  eStoppedReasonPause,
  eStoppedReasonEntry,
  eStoppedReasonGoto,
  eStoppedReasonFunctionBreakpoint,
  eStoppedReasonDataBreakpoint,
  eStoppedReasonInstructionBreakpoint,
};

/// The event indicates that the execution of the debuggee has stopped due to
/// some condition.
///
/// This can be caused by a breakpoint previously set, a stepping request has
/// completed, by executing a debugger statement etc.
struct StoppedEventBody {
  /// The reason for the event.
  ///
  /// For backward compatibility this string is shown in the UI if the
  /// `description` attribute is missing (but it must not be translated).
  StoppedReason reason = eStoppedReasonUninitialized;

  /// The full reason for the event, e.g. 'Paused on exception'. This string is
  /// shown in the UI as is and can be translated.
  std::string description;

  /// The thread which was stopped.
  lldb::tid_t threadId = LLDB_INVALID_THREAD_ID;

  /// A value of true hints to the client that this event should not change the
  /// focus.
  bool preserveFocusHint = false;

  /// Additional information. E.g. if reason is `exception`, text contains the
  /// exception name. This string is shown in the UI.
  std::string text;

  /// "If `allThreadsStopped` is true, a debug adapter can announce that all
  /// threads have stopped.
  ///
  /// - The client should use this information to enable that all threads can be
  /// expanded to access their stacktraces.
  /// - If the attribute is missing or false, only the thread with the given
  /// `threadId` can be expanded.
  bool allThreadsStopped = false;

  /// Ids of the breakpoints that triggered the event. In most cases there is
  /// only a single breakpoint but here are some examples for multiple
  /// breakpoints:
  ///
  /// - Different types of breakpoints map to the same location.
  /// - Multiple source breakpoints get collapsed to the same instruction by the
  /// compiler/runtime.
  /// - Multiple function breakpoints with different function names map to the
  /// same location.
  std::vector<lldb::break_id_t> hitBreakpointIds;
};
llvm::json::Value toJSON(const StoppedEventBody &);

} // end namespace lldb_dap::protocol

#endif