Line data Source code
1 : // Copyright 2016 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 : #ifndef V8_DEBUG_DEBUG_INTERFACE_H_
6 : #define V8_DEBUG_DEBUG_INTERFACE_H_
7 :
8 : #include "include/v8-inspector.h"
9 : #include "include/v8-util.h"
10 : #include "include/v8.h"
11 :
12 : #include "src/debug/interface-types.h"
13 : #include "src/globals.h"
14 :
15 : namespace v8 {
16 :
17 : namespace internal {
18 : struct CoverageBlock;
19 : struct CoverageFunction;
20 : struct CoverageScript;
21 : struct TypeProfileEntry;
22 : struct TypeProfileScript;
23 : class Coverage;
24 : class PostponeInterruptsScope;
25 : class Script;
26 : class TypeProfile;
27 : } // namespace internal
28 :
29 : namespace debug {
30 :
31 : void SetContextId(Local<Context> context, int id);
32 : int GetContextId(Local<Context> context);
33 :
34 : void SetInspector(Isolate* isolate, v8_inspector::V8Inspector*);
35 : v8_inspector::V8Inspector* GetInspector(Isolate* isolate);
36 :
37 : // Schedule a debugger break to happen when function is called inside given
38 : // isolate.
39 : void SetBreakOnNextFunctionCall(Isolate* isolate);
40 :
41 : // Remove scheduled debugger break in given isolate if it has not
42 : // happened yet.
43 : void ClearBreakOnNextFunctionCall(Isolate* isolate);
44 :
45 : /**
46 : * Returns array of internal properties specific to the value type. Result has
47 : * the following format: [<name>, <value>,...,<name>, <value>]. Result array
48 : * will be allocated in the current context.
49 : */
50 : MaybeLocal<Array> GetInternalProperties(Isolate* isolate, Local<Value> value);
51 :
52 : /**
53 : * Returns array of private fields specific to the value type. Result has
54 : * the following format: [<name>, <value>,...,<name>, <value>]. Result array
55 : * will be allocated in the current context.
56 : */
57 : MaybeLocal<Array> GetPrivateFields(Local<Context> context, Local<Object> value);
58 :
59 : enum ExceptionBreakState {
60 : NoBreakOnException = 0,
61 : BreakOnUncaughtException = 1,
62 : BreakOnAnyException = 2
63 : };
64 :
65 : /**
66 : * Defines if VM will pause on exceptions or not.
67 : * If BreakOnAnyExceptions is set then VM will pause on caught and uncaught
68 : * exception, if BreakOnUncaughtException is set then VM will pause only on
69 : * uncaught exception, otherwise VM won't stop on any exception.
70 : */
71 : void ChangeBreakOnException(Isolate* isolate, ExceptionBreakState state);
72 :
73 : void RemoveBreakpoint(Isolate* isolate, BreakpointId id);
74 : void SetBreakPointsActive(Isolate* isolate, bool is_active);
75 :
76 : enum StepAction {
77 : StepOut = 0, // Step out of the current function.
78 : StepNext = 1, // Step to the next statement in the current function.
79 : StepIn = 2 // Step into new functions invoked or the next statement
80 : // in the current function.
81 : };
82 :
83 : void PrepareStep(Isolate* isolate, StepAction action);
84 : void ClearStepping(Isolate* isolate);
85 : void BreakRightNow(Isolate* isolate);
86 :
87 : bool AllFramesOnStackAreBlackboxed(Isolate* isolate);
88 :
89 : class Script;
90 :
91 1522 : struct LiveEditResult {
92 : enum Status {
93 : OK,
94 : COMPILE_ERROR,
95 : BLOCKED_BY_RUNNING_GENERATOR,
96 : BLOCKED_BY_FUNCTION_ABOVE_BREAK_FRAME,
97 : BLOCKED_BY_FUNCTION_BELOW_NON_DROPPABLE_FRAME,
98 : BLOCKED_BY_ACTIVE_FUNCTION,
99 : BLOCKED_BY_NEW_TARGET_IN_RESTART_FRAME,
100 : FRAME_RESTART_IS_NOT_SUPPORTED
101 : };
102 : Status status = OK;
103 : bool stack_changed = false;
104 : // Available only for OK.
105 : v8::Local<v8::debug::Script> script;
106 : // Fields below are available only for COMPILE_ERROR.
107 : v8::Local<v8::String> message;
108 : int line_number = -1;
109 : int column_number = -1;
110 : };
111 :
112 : /**
113 : * Native wrapper around v8::internal::Script object.
114 : */
115 : class V8_EXPORT_PRIVATE Script {
116 : public:
117 : v8::Isolate* GetIsolate() const;
118 :
119 : ScriptOriginOptions OriginOptions() const;
120 : bool WasCompiled() const;
121 : bool IsEmbedded() const;
122 : int Id() const;
123 : int LineOffset() const;
124 : int ColumnOffset() const;
125 : std::vector<int> LineEnds() const;
126 : MaybeLocal<String> Name() const;
127 : MaybeLocal<String> SourceURL() const;
128 : MaybeLocal<String> SourceMappingURL() const;
129 : Maybe<int> ContextId() const;
130 : MaybeLocal<String> Source() const;
131 : bool IsWasm() const;
132 : bool IsModule() const;
133 : bool GetPossibleBreakpoints(
134 : const debug::Location& start, const debug::Location& end,
135 : bool restrict_to_function,
136 : std::vector<debug::BreakLocation>* locations) const;
137 : int GetSourceOffset(const debug::Location& location) const;
138 : v8::debug::Location GetSourceLocation(int offset) const;
139 : bool SetScriptSource(v8::Local<v8::String> newSource, bool preview,
140 : LiveEditResult* result) const;
141 : bool SetBreakpoint(v8::Local<v8::String> condition, debug::Location* location,
142 : BreakpointId* id) const;
143 : };
144 :
145 : // Specialization for wasm Scripts.
146 : class WasmScript : public Script {
147 : public:
148 : static WasmScript* Cast(Script* script);
149 :
150 : int NumFunctions() const;
151 : int NumImportedFunctions() const;
152 :
153 : std::pair<int, int> GetFunctionRange(int function_index) const;
154 :
155 : debug::WasmDisassembly DisassembleFunction(int function_index) const;
156 : uint32_t GetFunctionHash(int function_index);
157 : };
158 :
159 : void GetLoadedScripts(Isolate* isolate, PersistentValueVector<Script>& scripts);
160 :
161 : MaybeLocal<UnboundScript> CompileInspectorScript(Isolate* isolate,
162 : Local<String> source);
163 :
164 : enum ExceptionType { kException, kPromiseRejection };
165 :
166 3734 : class DebugDelegate {
167 : public:
168 4747664 : virtual ~DebugDelegate() = default;
169 3239 : virtual void ScriptCompiled(v8::Local<Script> script, bool is_live_edited,
170 3239 : bool has_compile_error) {}
171 : // |inspector_break_points_hit| contains id of breakpoints installed with
172 : // debug::Script::SetBreakpoint API.
173 10 : virtual void BreakProgramRequested(
174 : v8::Local<v8::Context> paused_context,
175 10 : const std::vector<debug::BreakpointId>& inspector_break_points_hit) {}
176 10 : virtual void ExceptionThrown(v8::Local<v8::Context> paused_context,
177 : v8::Local<v8::Value> exception,
178 : v8::Local<v8::Value> promise, bool is_uncaught,
179 10 : ExceptionType exception_type) {}
180 1284 : virtual bool IsFunctionBlackboxed(v8::Local<debug::Script> script,
181 : const debug::Location& start,
182 : const debug::Location& end) {
183 1284 : return false;
184 : }
185 : };
186 :
187 : void SetDebugDelegate(Isolate* isolate, DebugDelegate* listener);
188 :
189 3672 : class AsyncEventDelegate {
190 : public:
191 3672 : virtual ~AsyncEventDelegate() = default;
192 : virtual void AsyncEventOccurred(debug::DebugAsyncActionType type, int id,
193 : bool is_blackboxed) = 0;
194 : };
195 :
196 : void SetAsyncEventDelegate(Isolate* isolate, AsyncEventDelegate* delegate);
197 :
198 : void ResetBlackboxedStateCache(Isolate* isolate,
199 : v8::Local<debug::Script> script);
200 :
201 : int EstimatedValueSize(Isolate* isolate, v8::Local<v8::Value> value);
202 :
203 : enum Builtin { kStringToLowerCase };
204 :
205 : Local<Function> GetBuiltin(Isolate* isolate, Builtin builtin);
206 :
207 : V8_EXPORT_PRIVATE void SetConsoleDelegate(Isolate* isolate,
208 : ConsoleDelegate* delegate);
209 :
210 : int GetStackFrameId(v8::Local<v8::StackFrame> frame);
211 :
212 : v8::Local<v8::StackTrace> GetDetailedStackTrace(Isolate* isolate,
213 : v8::Local<v8::Object> error);
214 :
215 : /**
216 : * Native wrapper around v8::internal::JSGeneratorObject object.
217 : */
218 : class GeneratorObject {
219 : public:
220 : v8::MaybeLocal<debug::Script> Script();
221 : v8::Local<v8::Function> Function();
222 : debug::Location SuspendedLocation();
223 : bool IsSuspended();
224 :
225 : static v8::Local<debug::GeneratorObject> Cast(v8::Local<v8::Value> value);
226 : };
227 :
228 : /*
229 : * Provide API layer between inspector and code coverage.
230 : */
231 151 : class V8_EXPORT_PRIVATE Coverage {
232 : public:
233 : MOVE_ONLY_NO_DEFAULT_CONSTRUCTOR(Coverage);
234 :
235 : // Forward declarations.
236 : class ScriptData;
237 : class FunctionData;
238 :
239 32 : class V8_EXPORT_PRIVATE BlockData {
240 : public:
241 : MOVE_ONLY_NO_DEFAULT_CONSTRUCTOR(BlockData);
242 :
243 : int StartOffset() const;
244 : int EndOffset() const;
245 : uint32_t Count() const;
246 :
247 : private:
248 : explicit BlockData(i::CoverageBlock* block,
249 : std::shared_ptr<i::Coverage> coverage)
250 32 : : block_(block), coverage_(std::move(coverage)) {}
251 :
252 : i::CoverageBlock* block_;
253 : std::shared_ptr<i::Coverage> coverage_;
254 :
255 : friend class v8::debug::Coverage::FunctionData;
256 : };
257 :
258 415 : class V8_EXPORT_PRIVATE FunctionData {
259 : public:
260 : MOVE_ONLY_NO_DEFAULT_CONSTRUCTOR(FunctionData);
261 :
262 : int StartOffset() const;
263 : int EndOffset() const;
264 : uint32_t Count() const;
265 : MaybeLocal<String> Name() const;
266 : size_t BlockCount() const;
267 : bool HasBlockCoverage() const;
268 : BlockData GetBlockData(size_t i) const;
269 :
270 : private:
271 : explicit FunctionData(i::CoverageFunction* function,
272 : std::shared_ptr<i::Coverage> coverage)
273 405 : : function_(function), coverage_(std::move(coverage)) {}
274 :
275 : i::CoverageFunction* function_;
276 : std::shared_ptr<i::Coverage> coverage_;
277 :
278 : friend class v8::debug::Coverage::ScriptData;
279 : };
280 :
281 175 : class V8_EXPORT_PRIVATE ScriptData {
282 : public:
283 : MOVE_ONLY_NO_DEFAULT_CONSTRUCTOR(ScriptData);
284 :
285 : Local<debug::Script> GetScript() const;
286 : size_t FunctionCount() const;
287 : FunctionData GetFunctionData(size_t i) const;
288 :
289 : private:
290 : explicit ScriptData(size_t index, std::shared_ptr<i::Coverage> c);
291 :
292 : i::CoverageScript* script_;
293 : std::shared_ptr<i::Coverage> coverage_;
294 :
295 : friend class v8::debug::Coverage;
296 : };
297 :
298 : static Coverage CollectPrecise(Isolate* isolate);
299 : static Coverage CollectBestEffort(Isolate* isolate);
300 :
301 : static void SelectMode(Isolate* isolate, CoverageMode mode);
302 :
303 : size_t ScriptCount() const;
304 : ScriptData GetScriptData(size_t i) const;
305 : bool IsEmpty() const { return coverage_ == nullptr; }
306 :
307 : private:
308 : explicit Coverage(std::shared_ptr<i::Coverage> coverage)
309 : : coverage_(std::move(coverage)) {}
310 : std::shared_ptr<i::Coverage> coverage_;
311 : };
312 :
313 : /*
314 : * Provide API layer between inspector and type profile.
315 : */
316 40 : class V8_EXPORT_PRIVATE TypeProfile {
317 : public:
318 : MOVE_ONLY_NO_DEFAULT_CONSTRUCTOR(TypeProfile);
319 :
320 : class ScriptData; // Forward declaration.
321 :
322 456 : class V8_EXPORT_PRIVATE Entry {
323 : public:
324 308 : MOVE_ONLY_NO_DEFAULT_CONSTRUCTOR(Entry);
325 :
326 : int SourcePosition() const;
327 : std::vector<MaybeLocal<String>> Types() const;
328 :
329 : private:
330 : explicit Entry(const i::TypeProfileEntry* entry,
331 : std::shared_ptr<i::TypeProfile> type_profile)
332 148 : : entry_(entry), type_profile_(std::move(type_profile)) {}
333 :
334 : const i::TypeProfileEntry* entry_;
335 : std::shared_ptr<i::TypeProfile> type_profile_;
336 :
337 : friend class v8::debug::TypeProfile::ScriptData;
338 : };
339 :
340 32 : class V8_EXPORT_PRIVATE ScriptData {
341 : public:
342 : MOVE_ONLY_NO_DEFAULT_CONSTRUCTOR(ScriptData);
343 :
344 : Local<debug::Script> GetScript() const;
345 : std::vector<Entry> Entries() const;
346 :
347 : private:
348 : explicit ScriptData(size_t index,
349 : std::shared_ptr<i::TypeProfile> type_profile);
350 :
351 : i::TypeProfileScript* script_;
352 : std::shared_ptr<i::TypeProfile> type_profile_;
353 :
354 : friend class v8::debug::TypeProfile;
355 : };
356 :
357 : static TypeProfile Collect(Isolate* isolate);
358 :
359 : static void SelectMode(Isolate* isolate, TypeProfileMode mode);
360 :
361 : size_t ScriptCount() const;
362 : ScriptData GetScriptData(size_t i) const;
363 :
364 : private:
365 : explicit TypeProfile(std::shared_ptr<i::TypeProfile> type_profile)
366 : : type_profile_(std::move(type_profile)) {}
367 :
368 : std::shared_ptr<i::TypeProfile> type_profile_;
369 : };
370 :
371 : class ScopeIterator {
372 : public:
373 : static std::unique_ptr<ScopeIterator> CreateForFunction(
374 : v8::Isolate* isolate, v8::Local<v8::Function> func);
375 : static std::unique_ptr<ScopeIterator> CreateForGeneratorObject(
376 : v8::Isolate* isolate, v8::Local<v8::Object> generator);
377 :
378 147481 : ScopeIterator() = default;
379 147481 : virtual ~ScopeIterator() = default;
380 :
381 : enum ScopeType {
382 : ScopeTypeGlobal = 0,
383 : ScopeTypeLocal,
384 : ScopeTypeWith,
385 : ScopeTypeClosure,
386 : ScopeTypeCatch,
387 : ScopeTypeBlock,
388 : ScopeTypeScript,
389 : ScopeTypeEval,
390 : ScopeTypeModule
391 : };
392 :
393 : virtual bool Done() = 0;
394 : virtual void Advance() = 0;
395 : virtual ScopeType GetType() = 0;
396 : virtual v8::Local<v8::Object> GetObject() = 0;
397 : virtual v8::Local<v8::Value> GetFunctionDebugName() = 0;
398 : virtual int GetScriptId() = 0;
399 : virtual bool HasLocationInfo() = 0;
400 : virtual debug::Location GetStartLocation() = 0;
401 : virtual debug::Location GetEndLocation() = 0;
402 :
403 : virtual bool SetVariableValue(v8::Local<v8::String> name,
404 : v8::Local<v8::Value> value) = 0;
405 :
406 : private:
407 : DISALLOW_COPY_AND_ASSIGN(ScopeIterator);
408 : };
409 :
410 : class StackTraceIterator {
411 : public:
412 : static std::unique_ptr<StackTraceIterator> Create(Isolate* isolate,
413 : int index = 0);
414 111672 : StackTraceIterator() = default;
415 111672 : virtual ~StackTraceIterator() = default;
416 :
417 : virtual bool Done() const = 0;
418 : virtual void Advance() = 0;
419 :
420 : virtual int GetContextId() const = 0;
421 : virtual v8::MaybeLocal<v8::Value> GetReceiver() const = 0;
422 : virtual v8::Local<v8::Value> GetReturnValue() const = 0;
423 : virtual v8::Local<v8::String> GetFunctionDebugName() const = 0;
424 : virtual v8::Local<v8::debug::Script> GetScript() const = 0;
425 : virtual debug::Location GetSourceLocation() const = 0;
426 : virtual v8::Local<v8::Function> GetFunction() const = 0;
427 : virtual std::unique_ptr<ScopeIterator> GetScopeIterator() const = 0;
428 :
429 : virtual bool Restart() = 0;
430 : virtual v8::MaybeLocal<v8::Value> Evaluate(v8::Local<v8::String> source,
431 : bool throw_on_side_effect) = 0;
432 :
433 : private:
434 : DISALLOW_COPY_AND_ASSIGN(StackTraceIterator);
435 : };
436 :
437 85 : class QueryObjectPredicate {
438 : public:
439 85 : virtual ~QueryObjectPredicate() = default;
440 : virtual bool Filter(v8::Local<v8::Object> object) = 0;
441 : };
442 :
443 : void QueryObjects(v8::Local<v8::Context> context,
444 : QueryObjectPredicate* predicate,
445 : v8::PersistentValueVector<v8::Object>* objects);
446 :
447 : void GlobalLexicalScopeNames(v8::Local<v8::Context> context,
448 : v8::PersistentValueVector<v8::String>* names);
449 :
450 : void SetReturnValue(v8::Isolate* isolate, v8::Local<v8::Value> value);
451 :
452 : enum class NativeAccessorType {
453 : None = 0,
454 : HasGetter = 1 << 0,
455 : HasSetter = 1 << 1
456 : };
457 :
458 : int64_t GetNextRandomInt64(v8::Isolate* isolate);
459 :
460 : v8::MaybeLocal<v8::Value> EvaluateGlobal(v8::Isolate* isolate,
461 : v8::Local<v8::String> source,
462 : bool throw_on_side_effect);
463 :
464 : int GetDebuggingId(v8::Local<v8::Function> function);
465 :
466 : bool SetFunctionBreakpoint(v8::Local<v8::Function> function,
467 : v8::Local<v8::String> condition, BreakpointId* id);
468 :
469 : v8::Platform* GetCurrentPlatform();
470 :
471 0 : class PostponeInterruptsScope {
472 : public:
473 : explicit PostponeInterruptsScope(v8::Isolate* isolate);
474 : ~PostponeInterruptsScope();
475 :
476 : private:
477 : std::unique_ptr<i::PostponeInterruptsScope> scope_;
478 : };
479 :
480 : class WeakMap : public v8::Object {
481 : public:
482 : V8_WARN_UNUSED_RESULT v8::MaybeLocal<v8::Value> Get(
483 : v8::Local<v8::Context> context, v8::Local<v8::Value> key);
484 : V8_WARN_UNUSED_RESULT v8::MaybeLocal<WeakMap> Set(
485 : v8::Local<v8::Context> context, v8::Local<v8::Value> key,
486 : v8::Local<v8::Value> value);
487 :
488 : static Local<WeakMap> New(v8::Isolate* isolate);
489 : V8_INLINE static WeakMap* Cast(Value* obj);
490 :
491 : private:
492 : WeakMap();
493 : };
494 :
495 : struct PropertyDescriptor {
496 : bool enumerable : 1;
497 : bool has_enumerable : 1;
498 : bool configurable : 1;
499 : bool has_configurable : 1;
500 : bool writable : 1;
501 : bool has_writable : 1;
502 : v8::Local<v8::Value> value;
503 : v8::Local<v8::Value> get;
504 : v8::Local<v8::Value> set;
505 : };
506 :
507 79268 : class PropertyIterator {
508 : public:
509 : static std::unique_ptr<PropertyIterator> Create(v8::Local<v8::Object> object);
510 :
511 79268 : virtual ~PropertyIterator() = default;
512 :
513 : virtual bool Done() const = 0;
514 : virtual void Advance() = 0;
515 :
516 : virtual v8::Local<v8::Name> name() const = 0;
517 :
518 : virtual bool is_native_accessor() = 0;
519 : virtual bool has_native_getter() = 0;
520 : virtual bool has_native_setter() = 0;
521 : virtual Maybe<PropertyAttribute> attributes() = 0;
522 : virtual Maybe<PropertyDescriptor> descriptor() = 0;
523 :
524 : virtual bool is_own() = 0;
525 : virtual bool is_array_index() = 0;
526 : };
527 : } // namespace debug
528 : } // namespace v8
529 :
530 : #endif // V8_DEBUG_DEBUG_INTERFACE_H_
|
