Add comments to test-log-stack-tracer.

test/cctest/test-log-stack-tracer.cc

 // Copyright 2006-2009 the V8 project authors. All rights reserved.
 //
 // Tests of profiler-related functions from log.h
 
 #ifdef ENABLE_LOGGING_AND_PROFILING
 
 #include <stdlib.h>
 
 #include "v8.h"
 
@@ skipping 266 matching lines @@
   v8::internal::Code* func_code = func->code();
   CHECK(func_code->IsCode());
   func_code->Print();
 #endif
 
   SetGlobalProperty(func_name, v8::ToApi<Value>(func));
   CHECK_EQ(*func, *GetGlobalJSFunction(func_name));
 }
 
 
+// This test verifies that stack tracing works when called during
+// execution of a native function called from JS code. In this case,
+// StackTracer uses Top::c_entry_fp as a starting point for stack
+// walking.
 TEST(CFromJSStackTrace) {
   TickSample sample;
   InitTraceEnv(&sample);
 
   InitializeVM();
   v8::HandleScope scope;
+  // Create global function JSFuncDoTrace which calls
+  // extension function trace() with the current frame pointer value.
   CreateTraceCallerFunction("JSFuncDoTrace", "trace");
   Local<Value> result = CompileRun(
       "function JSTrace() {"
       "         JSFuncDoTrace();"
       "};\n"
       "JSTrace();\n"
       "true;");
   CHECK(!result.IsEmpty());
+  // When stack tracer is invoked, the stack should look as follows:
+  // script [JS]
+  //   JSTrace() [JS]
+  //     JSFuncDoTrace() [JS] [captures EBP value and encodes it as Smi]
+  //       trace(EBP encoded as Smi) [native (extension)]
+  //         DoTrace(EBP) [native]
+  //           StackTracer::Trace
   CHECK_GT(sample.frames_count, 1);
-  // Stack sampling will start from the first JS function, i.e. "JSFuncDoTrace"
+  // Stack tracing will start from the first JS function, i.e. "JSFuncDoTrace"
   CheckRetAddrIsInJSFunction("JSFuncDoTrace",
                              sample.stack[0]);
   CheckRetAddrIsInJSFunction("JSTrace",
                              sample.stack[1]);
 }
 
 
+// This test verifies that stack tracing works when called during
+// execution of JS code. However, as calling StackTracer requires
+// entering native code, we can only emulate pure JS by erasing
+// Top::c_entry_fp value. In this case, StackTracer uses passed frame
+// pointer value as a starting point for stack walking.
 TEST(PureJSStackTrace) {
   TickSample sample;
   InitTraceEnv(&sample);
 
   InitializeVM();
   v8::HandleScope scope;
+  // Create global function JSFuncDoTrace which calls
+  // extension function js_trace() with the current frame pointer value.
   CreateTraceCallerFunction("JSFuncDoTrace", "js_trace");
   Local<Value> result = CompileRun(
       "function JSTrace() {"
       "         JSFuncDoTrace();"
       "};\n"
       "function OuterJSTrace() {"
       "         JSTrace();"
       "};\n"
       "OuterJSTrace();\n"
       "true;");
   CHECK(!result.IsEmpty());
-  // The last JS function called.
+  // When stack tracer is invoked, the stack should look as follows:
+  // script [JS]
+  //   OuterJSTrace() [JS]
+  //     JSTrace() [JS]
+  //       JSFuncDoTrace() [JS] [captures EBP value and encodes it as Smi]
+  //         js_trace(EBP encoded as Smi) [native (extension)]
+  //           DoTraceHideCEntryFPAddress(EBP) [native]
+  //             StackTracer::Trace
+  //
+  // The last JS function called. It is only visible through
+  // sample.function, as its return address is above captured EBP value.
   CHECK_EQ(GetGlobalJSFunction("JSFuncDoTrace")->address(),
            sample.function);
   CHECK_GT(sample.frames_count, 1);
   // Stack sampling will start from the caller of JSFuncDoTrace, i.e. "JSTrace"
   CheckRetAddrIsInJSFunction("JSTrace",
                              sample.stack[0]);
   CheckRetAddrIsInJSFunction("OuterJSTrace",
                              sample.stack[1]);
 }
 
@@ skipping 16 matching lines @@
 static int CFunc(int depth) {
   if (depth <= 0) {
     CFuncDoTrace(0);
     return 0;
   } else {
     return CFunc(depth - 1) + 1;
   }
 }
 
 
+// This test verifies that stack tracing doesn't crash when called on
+// pure native code. StackTracer only unrolls JS code, so we can't
+// get any meaningful info here.
 TEST(PureCStackTrace) {
   TickSample sample;
   InitTraceEnv(&sample);
   // Check that sampler doesn't crash
   CHECK_EQ(10, CFunc(10));
 }
 
 
 TEST(JsEntrySp) {
   InitializeVM();
   v8::HandleScope scope;
   CHECK_EQ(0, GetJsEntrySp());
   CompileRun("a = 1; b = a + 1;");
   CHECK_EQ(0, GetJsEntrySp());
   CompileRun("js_entry_sp();");
   CHECK_EQ(0, GetJsEntrySp());
   CompileRun("js_entry_sp_level2();");
   CHECK_EQ(0, GetJsEntrySp());
 }
 
 #endif  // ENABLE_LOGGING_AND_PROFILING