123 lines · c
1//===-- ProtocolEvents.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 POD structs based on the DAP specification at10// https://microsoft.github.io/debug-adapter-protocol/specification11//12// This is not meant to be a complete implementation, new interfaces are added13// when they're needed.14//15// Each struct has a toJSON and fromJSON function, that converts between16// the struct and a JSON representation. (See JSON.h)17//18//===----------------------------------------------------------------------===//19 20#ifndef LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_EVENTS_H21#define LLDB_TOOLS_LLDB_DAP_PROTOCOL_PROTOCOL_EVENTS_H22 23#include "Protocol/ProtocolTypes.h"24#include "lldb/lldb-defines.h"25#include "lldb/lldb-types.h"26#include "llvm/Support/JSON.h"27#include <cstdint>28#include <optional>29#include <vector>30 31namespace lldb_dap::protocol {32 33/// The event indicates that one or more capabilities have changed.34///35/// Since the capabilities are dependent on the client and its UI, it might not36/// be possible to change that at random times (or too late).37///38/// Consequently this event has a hint characteristic: a client can only be39/// expected to make a 'best effort' in honoring individual capabilities but40/// there are no guarantees.41///42/// Only changed capabilities need to be included, all other capabilities keep43/// their values.44struct CapabilitiesEventBody {45 Capabilities capabilities;46};47llvm::json::Value toJSON(const CapabilitiesEventBody &);48 49/// The event indicates that some information about a module has changed.50struct ModuleEventBody {51 enum Reason : unsigned { eReasonNew, eReasonChanged, eReasonRemoved };52 53 /// The new, changed, or removed module. In case of `removed` only the module54 /// id is used.55 Module module;56 57 /// The reason for the event.58 /// Values: 'new', 'changed', 'removed'59 Reason reason;60};61llvm::json::Value toJSON(const ModuleEventBody::Reason &);62llvm::json::Value toJSON(const ModuleEventBody &);63 64/// This event signals that some state in the debug adapter has changed and65/// requires that the client needs to re-render the data snapshot previously66/// requested.67///68/// Debug adapters do not have to emit this event for runtime changes like69/// stopped or thread events because in that case the client refetches the new70/// state anyway. But the event can be used for example to refresh the UI after71/// rendering formatting has changed in the debug adapter.72///73/// This event should only be sent if the corresponding capability74/// supportsInvalidatedEvent is true.75struct InvalidatedEventBody {76 enum Area : unsigned { eAreaAll, eAreaStacks, eAreaThreads, eAreaVariables };77 78 /// Set of logical areas that got invalidated.79 std::vector<Area> areas;80 81 /// If specified, the client only needs to refetch data related to this82 /// thread.83 std::optional<lldb::tid_t> threadId;84 85 /// If specified, the client only needs to refetch data related to this stack86 /// frame (and the `threadId` is ignored).87 std::optional<uint64_t> stackFrameId;88};89llvm::json::Value toJSON(const InvalidatedEventBody::Area &);90llvm::json::Value toJSON(const InvalidatedEventBody &);91 92/// This event indicates that some memory range has been updated. It should only93/// be sent if the corresponding capability supportsMemoryEvent is true.94///95/// Clients typically react to the event by re-issuing a readMemory request if96/// they show the memory identified by the memoryReference and if the updated97/// memory range overlaps the displayed range. Clients should not make98/// assumptions how individual memory references relate to each other, so they99/// should not assume that they are part of a single continuous address range100/// and might overlap.101///102/// Debug adapters can use this event to indicate that the contents of a memory103/// range has changed due to some other request like setVariable or104/// setExpression. Debug adapters are not expected to emit this event for each105/// and every memory change of a running program, because that information is106/// typically not available from debuggers and it would flood clients with too107/// many events.108struct MemoryEventBody {109 /// Memory reference of a memory range that has been updated.110 lldb::addr_t memoryReference = LLDB_INVALID_ADDRESS;111 112 /// Starting offset in bytes where memory has been updated. Can be negative.113 int64_t offset = 0;114 115 /// Number of bytes updated.116 uint64_t count = 0;117};118llvm::json::Value toJSON(const MemoryEventBody &);119 120} // end namespace lldb_dap::protocol121 122#endif123