1// Copyright 2019 the V8 project authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// This file defines the public interface to v8_debug_helper.
6
7#ifndef V8_TOOLS_DEBUG_HELPER_DEBUG_HELPER_H_
8#define V8_TOOLS_DEBUG_HELPER_DEBUG_HELPER_H_
9
10#include <cstdint>
11#include <memory>
12
13#if defined(_WIN32)
14
15#ifdef BUILDING_V8_DEBUG_HELPER
16#define V8_DEBUG_HELPER_EXPORT __declspec(dllexport)
17#elif USING_V8_DEBUG_HELPER
18#define V8_DEBUG_HELPER_EXPORT __declspec(dllimport)
19#else
20#define V8_DEBUG_HELPER_EXPORT
21#endif
22
23#else  // defined(_WIN32)
24
25#ifdef BUILDING_V8_DEBUG_HELPER
26#define V8_DEBUG_HELPER_EXPORT __attribute__((visibility("default")))
27#else
28#define V8_DEBUG_HELPER_EXPORT
29#endif
30
31#endif  // defined(_WIN32)
32
33namespace v8 {
34namespace debug_helper {
35
36// Possible results when attempting to fetch memory from the debuggee.
37enum class MemoryAccessResult {
38  kOk,
39  kAddressNotValid,
40  kAddressValidButInaccessible,  // Possible in incomplete dump.
41};
42
43// Information about how this tool discovered the type of the object.
44enum class TypeCheckResult {
45  // Success cases:
46  kSmi,
47  kWeakRef,
48  kUsedMap,
49  kKnownMapPointer,
50  kUsedTypeHint,
51
52  // Failure cases:
53  kUnableToDecompress,  // Caller must provide the heap range somehow.
54  kObjectPointerInvalid,
55  kObjectPointerValidButInaccessible,  // Possible in incomplete dump.
56  kMapPointerInvalid,
57  kMapPointerValidButInaccessible,  // Possible in incomplete dump.
58  kUnknownInstanceType,
59  kUnknownTypeHint,
60};
61
62enum class PropertyKind {
63  kSingle,
64  kArrayOfKnownSize,
65  kArrayOfUnknownSizeDueToInvalidMemory,
66  kArrayOfUnknownSizeDueToValidButInaccessibleMemory,
67};
68
69struct PropertyBase {
70  const char* name;
71
72  // Statically-determined type, such as from .tq definition. Can be an empty
73  // string if this property is itself a Torque-defined struct; in that case use
74  // |struct_fields| instead. This type should be treated as if it were used in
75  // the v8::internal namespace; that is, type "X::Y" can mean any of the
76  // following, in order of decreasing preference:
77  // - v8::internal::X::Y
78  // - v8::X::Y
79  // - X::Y
80  const char* type;
81
82  // In some cases, |type| may be a simple type representing a compressed
83  // pointer such as v8::internal::TaggedValue. In those cases,
84  // |decompressed_type| will contain the type of the object when decompressed.
85  // Otherwise, |decompressed_type| will match |type|. In any case, it is safe
86  // to pass the |decompressed_type| value as the type_hint on a subsequent call
87  // to GetObjectProperties.
88  const char* decompressed_type;
89};
90
91struct StructProperty : public PropertyBase {
92  // The offset from the beginning of the struct to this field.
93  size_t offset;
94
95  // The number of bits that are present, if this value is a bitfield. Zero
96  // indicates that this value is not a bitfield (the full value is stored).
97  uint8_t num_bits;
98
99  // The number of bits by which this value has been left-shifted for storage as
100  // a bitfield.
101  uint8_t shift_bits;
102};
103
104struct ObjectProperty : public PropertyBase {
105  // The address where the property value can be found in the debuggee's address
106  // space, or the address of the first value for an array.
107  uintptr_t address;
108
109  // If kind indicates an array of unknown size, num_values will be 0 and debug
110  // tools should display this property as a raw pointer. Note that there is a
111  // semantic difference between num_values=1 and kind=kSingle (normal property)
112  // versus num_values=1 and kind=kArrayOfKnownSize (one-element array).
113  size_t num_values;
114
115  // The number of bytes occupied by a single instance of the value type for
116  // this property. This can also be used as the array stride because arrays are
117  // tightly packed like in C.
118  size_t size;
119
120  // If the property is a struct made up of several pieces of data packed
121  // together, then the |struct_fields| array contains descriptions of those
122  // fields.
123  size_t num_struct_fields;
124  StructProperty** struct_fields;
125
126  PropertyKind kind;
127};
128
129struct ObjectPropertiesResult {
130  TypeCheckResult type_check_result;
131  const char* brief;
132  const char* type;  // Runtime type of the object.
133  size_t num_properties;
134  ObjectProperty** properties;
135
136  // If not all relevant memory is available, GetObjectProperties may respond
137  // with a technically correct but uninteresting type such as HeapObject, and
138  // use other heuristics to make reasonable guesses about what specific type
139  // the object actually is. You may request data about the same object again
140  // using any of these guesses as the type hint, but the results should be
141  // formatted to the user in a way that clearly indicates that they're only
142  // guesses.
143  size_t num_guessed_types;
144  const char** guessed_types;
145};
146
147struct StackFrameResult {
148  size_t num_properties;
149  ObjectProperty** properties;
150};
151
152// Copies byte_count bytes of memory from the given address in the debuggee to
153// the destination buffer.
154typedef MemoryAccessResult (*MemoryAccessor)(uintptr_t address,
155                                             void* destination,
156                                             size_t byte_count);
157
158// Additional data that can help GetObjectProperties to be more accurate. Any
159// fields you don't know can be set to zero and this library will do the best it
160// can with the information available.
161struct HeapAddresses {
162  // Beginning of allocated space for various kinds of data. These can help us
163  // to detect certain common objects that are placed in memory during startup.
164  // These values might be provided via name-value pairs in CrashPad dumps.
165  // Otherwise, they can be obtained as follows:
166  // 1. Get the Isolate pointer for the current thread. It might be somewhere on
167  //    the stack, or it might be accessible from thread-local storage with the
168  //    key stored in v8::internal::Isolate::isolate_key_.
169  // 2. Get isolate->heap_.map_space_->memory_chunk_list_.front_ and similar for
170  //    old_space_ and read_only_space_.
171  uintptr_t map_space_first_page;
172  uintptr_t old_space_first_page;
173  uintptr_t read_only_space_first_page;
174
175  // Any valid heap pointer address. On platforms where pointer compression is
176  // enabled, this can allow us to get data from compressed pointers even if the
177  // other data above is not provided. The Isolate pointer is valid for this
178  // purpose if you have it.
179  uintptr_t any_heap_pointer;
180};
181
182// Result type for ListObjectClasses.
183struct ClassList {
184  size_t num_class_names;
185  const char* const* class_names;  // Fully qualified class names.
186};
187
188}  // namespace debug_helper
189}  // namespace v8
190
191extern "C" {
192// Raw library interface. If possible, use functions in v8::debug_helper
193// namespace instead because they use smart pointers to prevent leaks.
194V8_DEBUG_HELPER_EXPORT v8::debug_helper::ObjectPropertiesResult*
195_v8_debug_helper_GetObjectProperties(
196    uintptr_t object, v8::debug_helper::MemoryAccessor memory_accessor,
197    const v8::debug_helper::HeapAddresses& heap_addresses,
198    const char* type_hint);
199V8_DEBUG_HELPER_EXPORT void _v8_debug_helper_Free_ObjectPropertiesResult(
200    v8::debug_helper::ObjectPropertiesResult* result);
201V8_DEBUG_HELPER_EXPORT v8::debug_helper::StackFrameResult*
202_v8_debug_helper_GetStackFrame(
203    uintptr_t frame_pointer, v8::debug_helper::MemoryAccessor memory_accessor);
204V8_DEBUG_HELPER_EXPORT void _v8_debug_helper_Free_StackFrameResult(
205    v8::debug_helper::StackFrameResult* result);
206V8_DEBUG_HELPER_EXPORT const v8::debug_helper::ClassList*
207_v8_debug_helper_ListObjectClasses();
208V8_DEBUG_HELPER_EXPORT const char* _v8_debug_helper_BitsetName(
209    uint64_t payload);
210}
211
212namespace v8 {
213namespace debug_helper {
214
215struct DebugHelperObjectPropertiesResultDeleter {
216  void operator()(v8::debug_helper::ObjectPropertiesResult* ptr) {
217    _v8_debug_helper_Free_ObjectPropertiesResult(ptr);
218  }
219};
220using ObjectPropertiesResultPtr =
221    std::unique_ptr<ObjectPropertiesResult,
222                    DebugHelperObjectPropertiesResultDeleter>;
223
224// Get information about the given object pointer, which could be:
225// - A tagged pointer, strong or weak
226// - A cleared weak pointer
227// - A compressed tagged pointer, zero-extended to 64 bits
228// - A tagged small integer
229// The type hint is only used if the object's Map is missing or corrupt. It
230// should be the fully-qualified name of a class that inherits from
231// v8::internal::Object.
232inline ObjectPropertiesResultPtr GetObjectProperties(
233    uintptr_t object, v8::debug_helper::MemoryAccessor memory_accessor,
234    const HeapAddresses& heap_addresses, const char* type_hint = nullptr) {
235  return ObjectPropertiesResultPtr(_v8_debug_helper_GetObjectProperties(
236      object, memory_accessor, heap_addresses, type_hint));
237}
238
239// Get a list of all class names deriving from v8::internal::Object.
240inline const ClassList* ListObjectClasses() {
241  return _v8_debug_helper_ListObjectClasses();
242}
243
244// Return a bitset name for a v8::internal::compiler::Type with payload or null
245// if the payload is not a bitset.
246inline const char* BitsetName(uint64_t payload) {
247  return _v8_debug_helper_BitsetName(payload);
248}
249
250struct DebugHelperStackFrameResultDeleter {
251  void operator()(v8::debug_helper::StackFrameResult* ptr) {
252    _v8_debug_helper_Free_StackFrameResult(ptr);
253  }
254};
255using StackFrameResultPtr =
256    std::unique_ptr<StackFrameResult, DebugHelperStackFrameResultDeleter>;
257
258inline StackFrameResultPtr GetStackFrame(
259    uintptr_t frame_pointer, v8::debug_helper::MemoryAccessor memory_accessor) {
260  return StackFrameResultPtr(
261      _v8_debug_helper_GetStackFrame(frame_pointer, memory_accessor));
262}
263
264}  // namespace debug_helper
265}  // namespace v8
266
267#endif
268