|
| 1 | +//===----------------------------------------------------------------------===// |
| 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 | +#ifndef LLDB_TARGET_SYNTHETICFRAMEPROVIDER_H |
| 10 | +#define LLDB_TARGET_SYNTHETICFRAMEPROVIDER_H |
| 11 | + |
| 12 | +#include "lldb/Core/PluginInterface.h" |
| 13 | +#include "lldb/Target/StackFrameList.h" |
| 14 | +#include "lldb/Target/ThreadSpec.h" |
| 15 | +#include "lldb/Utility/ScriptedMetadata.h" |
| 16 | +#include "lldb/Utility/Status.h" |
| 17 | +#include "lldb/lldb-forward.h" |
| 18 | +#include "llvm/Support/Error.h" |
| 19 | + |
| 20 | +#include <optional> |
| 21 | +#include <vector> |
| 22 | + |
| 23 | +namespace lldb_private { |
| 24 | + |
| 25 | +/// This struct contains the metadata needed to instantiate a frame provider |
| 26 | +/// and optional filters to control which threads it applies to. |
| 27 | +struct SyntheticFrameProviderDescriptor { |
| 28 | + /// Metadata for instantiating the provider (e.g., script class name and args) |
| 29 | + lldb::ScriptedMetadataSP scripted_metadata_sp; |
| 30 | + |
| 31 | + /// Optional list of thread specifications to which this provider applies. |
| 32 | + /// If empty, the provider applies to all threads. A thread matches if it |
| 33 | + /// satisfies ANY of the specs in this vector (OR logic). |
| 34 | + std::vector<ThreadSpec> thread_specs; |
| 35 | + |
| 36 | + SyntheticFrameProviderDescriptor() = default; |
| 37 | + |
| 38 | + SyntheticFrameProviderDescriptor(lldb::ScriptedMetadataSP metadata_sp) |
| 39 | + : scripted_metadata_sp(metadata_sp) {} |
| 40 | + |
| 41 | + SyntheticFrameProviderDescriptor(lldb::ScriptedMetadataSP metadata_sp, |
| 42 | + const std::vector<ThreadSpec> &specs) |
| 43 | + : scripted_metadata_sp(metadata_sp), thread_specs(specs) {} |
| 44 | + |
| 45 | + virtual ~SyntheticFrameProviderDescriptor() = default; |
| 46 | + |
| 47 | + /// Get the name of this descriptor (the scripted class name). |
| 48 | + llvm::StringRef GetName() const { |
| 49 | + return scripted_metadata_sp ? scripted_metadata_sp->GetClassName() : ""; |
| 50 | + } |
| 51 | + |
| 52 | + /// Check if this descriptor applies to the given thread. |
| 53 | + bool AppliesToThread(Thread &thread) const { |
| 54 | + // If no thread specs specified, applies to all threads |
| 55 | + if (thread_specs.empty()) |
| 56 | + return true; |
| 57 | + |
| 58 | + // Check if the thread matches any of the specs (OR logic) |
| 59 | + for (const auto &spec : thread_specs) { |
| 60 | + if (spec.ThreadPassesBasicTests(thread)) |
| 61 | + return true; |
| 62 | + } |
| 63 | + return false; |
| 64 | + } |
| 65 | + |
| 66 | + /// Check if this descriptor has valid metadata for script-based providers. |
| 67 | + /// Note: For C++ plugins, the descriptor may not have scripted metadata. |
| 68 | + bool HasScriptedMetadata() const { return scripted_metadata_sp != nullptr; } |
| 69 | + |
| 70 | + /// Check if this descriptor is valid (deprecated - use HasScriptedMetadata). |
| 71 | + /// This method is kept for backward compatibility. |
| 72 | + virtual bool IsValid() const { return HasScriptedMetadata(); } |
| 73 | + |
| 74 | + void Dump(Stream *s) const; |
| 75 | +}; |
| 76 | + |
| 77 | +/// Base class for all synthetic frame providers. |
| 78 | +/// |
| 79 | +/// Synthetic frame providers allow modifying or replacing the stack frames |
| 80 | +/// shown for a thread. This is useful for: |
| 81 | +/// - Providing frames for custom calling conventions or languages |
| 82 | +/// - Reconstructing missing frames from crash dumps or core files |
| 83 | +/// - Adding diagnostic or synthetic frames for debugging |
| 84 | +/// - Visualizing state machines or async execution contexts |
| 85 | +class SyntheticFrameProvider : public PluginInterface { |
| 86 | +public: |
| 87 | + /// Try to create a SyntheticFrameProvider instance for the given input |
| 88 | + /// frames and descriptor. |
| 89 | + /// |
| 90 | + /// This method iterates through all registered SyntheticFrameProvider |
| 91 | + /// plugins and returns the first one that can handle the given descriptor. |
| 92 | + /// |
| 93 | + /// \param[in] input_frames |
| 94 | + /// The input stack frame list that this provider will transform. |
| 95 | + /// This could be real unwound frames or output from another provider. |
| 96 | + /// |
| 97 | + /// \param[in] descriptor |
| 98 | + /// The descriptor containing metadata for the provider. |
| 99 | + /// |
| 100 | + /// \return |
| 101 | + /// A shared pointer to a SyntheticFrameProvider if one could be created, |
| 102 | + /// otherwise an \a llvm::Error. |
| 103 | + static llvm::Expected<lldb::SyntheticFrameProviderSP> |
| 104 | + CreateInstance(lldb::StackFrameListSP input_frames, |
| 105 | + const SyntheticFrameProviderDescriptor &descriptor); |
| 106 | + |
| 107 | + /// Try to create a SyntheticFrameProvider instance for the given input |
| 108 | + /// frames using a specific C++ plugin. |
| 109 | + /// |
| 110 | + /// This method directly invokes a specific SyntheticFrameProvider plugin |
| 111 | + /// by name, bypassing the descriptor-based plugin iteration. This is useful |
| 112 | + /// for C++ plugins that don't require scripted metadata. |
| 113 | + /// |
| 114 | + /// \param[in] input_frames |
| 115 | + /// The input stack frame list that this provider will transform. |
| 116 | + /// This could be real unwound frames or output from another provider. |
| 117 | + /// |
| 118 | + /// \param[in] plugin_name |
| 119 | + /// The name of the plugin to use for creating the provider. |
| 120 | + /// |
| 121 | + /// \param[in] thread_specs |
| 122 | + /// Optional list of thread specifications to which this provider applies. |
| 123 | + /// If empty, the provider applies to all threads. |
| 124 | + /// |
| 125 | + /// \return |
| 126 | + /// A shared pointer to a SyntheticFrameProvider if one could be created, |
| 127 | + /// otherwise an \a llvm::Error. |
| 128 | + static llvm::Expected<lldb::SyntheticFrameProviderSP> |
| 129 | + CreateInstance(lldb::StackFrameListSP input_frames, |
| 130 | + llvm::StringRef plugin_name, |
| 131 | + const std::vector<ThreadSpec> &thread_specs = {}); |
| 132 | + |
| 133 | + ~SyntheticFrameProvider() override; |
| 134 | + |
| 135 | + /// Get a single stack frame at the specified index. |
| 136 | + /// |
| 137 | + /// This method is called lazily - frames are only created when requested. |
| 138 | + /// The provider can access its input frames via GetInputFrames() if needed. |
| 139 | + /// |
| 140 | + /// \param[in] idx |
| 141 | + /// The index of the frame to create. |
| 142 | + /// |
| 143 | + /// \return |
| 144 | + /// An Expected containing the StackFrameSP if successful. Returns an |
| 145 | + /// error when the index is beyond the last frame to signal the end of |
| 146 | + /// the frame list. |
| 147 | + virtual llvm::Expected<lldb::StackFrameSP> GetFrameAtIndex(uint32_t idx) = 0; |
| 148 | + |
| 149 | + /// Get the thread associated with this provider. |
| 150 | + Thread &GetThread() { return m_input_frames->GetThread(); } |
| 151 | + |
| 152 | + /// Get the input frames that this provider transforms. |
| 153 | + lldb::StackFrameListSP GetInputFrames() const { return m_input_frames; } |
| 154 | + |
| 155 | +protected: |
| 156 | + SyntheticFrameProvider(lldb::StackFrameListSP input_frames); |
| 157 | + |
| 158 | + lldb::StackFrameListSP m_input_frames; |
| 159 | +}; |
| 160 | + |
| 161 | +} // namespace lldb_private |
| 162 | + |
| 163 | +#endif // LLDB_TARGET_SYNTHETICFRAMEPROVIDER_H |
0 commit comments