1DESCRIPTION ------------------------------------------------------------------- 2 3gcmole is a simple static analysis tool used to find possible evaluation order 4dependent GC-unsafe places in the V8 codebase and "stale" pointers to the heap 5(ones whose addresses got invalidated by the GC). 6 7For example the following code is GC-unsafe: 8 9 Handle<Object> Foo(); // Assume Foo can trigger a GC. 10 void Bar(Object, Object); 11 12 Handle<Object> baz; 13 baz->Qux(*Foo()); // (a) 14 Bar(*Foo(), *baz); // (b) 15 16Both in cases (a) and (b) compiler is free to evaluate call arguments (that 17includes receiver) in any order. That means it can dereference baz before 18calling to Foo and save a raw pointer to a heap object in the register or 19on the stack. 20 21In terms of the AST analysis that gcmole does, it warns about places in the 22code which result in 2 subtrees, the order of execution of which is undefined 23by C++, one of which causes a GC and the other dereferences a Handle to a raw 24Object (or its subclasses). 25 26The following code triggers a stale variable warning (assuming that the Foo 27function was detected as potentially allocating, as in the previous example): 28 29 JSObject raw_obj = ...; 30 Foo(); 31 raw_obj.Print(); 32 33Since Foo can trigger a GC, it might have moved the raw_obj. The solution is 34simply to store it as a Handle. 35 36PREREQUISITES ----------------------------------------------------------------- 37 38(1) Install Python 39 40 $ sudo apt-get install python 41 42(2) Get LLVM 8.0 and Clang 8.0 sources and build them. 43 44 Follow the instructions on http://clang.llvm.org/get_started.html. 45 46 Make sure to pass -DCMAKE_BUILD_TYPE=Release to cmake to get Release build 47 instead of a Debug one. 48 49(3) Build gcmole Clang plugin (libgcmole.so) 50 51 In the tools/gcmole directory execute the following command: 52 53 $ BUILD_ROOT=<path> LLVM_SRC_ROOT=<path> CLANG_SRC_ROOT=<path> make 54 55(*) Note that steps (2) and (3) can also be achieved by just using the included 56 bootstrapping script in this directory: 57 58 $ ./tools/gcmole/bootstrap.sh 59 60 This will use "third_party/llvm+clang-build" as a build directory and checkout 61 required sources in the "third_party" directory. 62 63USING GCMOLE ------------------------------------------------------------------ 64 65gcmole consists of driver script written in Python and Clang plugin that does 66C++ AST processing. Plugin (libgcmole.so) is expected to be in the same 67folder as driver (gcmole.py). 68 69To start analysis cd into the root of v8 checkout and execute the following 70command: 71 72CLANG_BIN=<path-to-clang-bin-folder> python tools/gcmole/gcmole.py [<arch>] 73 74where arch should be one of architectures supported by V8 (arm, ia32, x64). 75 76Analysis will be performed in 2 stages: 77 78- on the first stage driver will parse all files and build a global callgraph 79approximation to find all functions that might potentially cause GC, list 80of this functions will be written into gcsuspects file. 81 82- on the second stage driver will parse all files again and will locate all 83callsites that might be GC-unsafe based on the list of functions causing GC. 84Such places are marked with a "Possible problem with evaluation order." 85warning. Messages "Failed to resolve v8::internal::Object" are benign and 86can be ignored. 87 88If any errors were found driver exits with non-zero status. 89 90TESTING ----------------------------------------------------------------------- 91 92Tests are automatically run by the main python runner. Expectations are in 93test-expectations.txt and need to be updated whenever the sources of the tests 94in gcmole-test.cc are modified (line numbers also count). 95 96PACKAGING --------------------------------------------------------------------- 97 98gcmole is deployed on V8's buildbot infrastructure to run it as part of the 99continuous integration. A pre-built package of gcmole together with Clang is 100hosted on Google Cloud Storage for this purpose. To update this package to a 101newer version, use the provided packaging script: 102 103 $ ./tools/gcmole/package.sh 104 105This will create a new "tools/gcmole/gcmole-tools.tar.gz" package with the 106corresponding SHA1 sum suitable to be used for this purpose. It assumes that 107Clang was built in "third_party/llvm+clang-build" (e.g. by the bootstrapping 108script "bootstrap.sh" mentioned above). 109 110TROUBLESHOOTING --------------------------------------------------------------- 111 112gcmole is tightly coupled with the AST structure that Clang produces. Therefore 113when upgrading to a newer Clang version, it might start producing bogus output 114or completely stop outputting warnings. In such occasion, one might start the 115debugging process by checking weather a new AST node type is introduced which 116is currently not supported by gcmole. Insert the following code at the end of 117the FunctionAnalyzer::VisitExpr method to see the unsupported AST class(es) 118and the source position which generates them: 119 120 if (expr) { 121 clang::Stmt::StmtClass stmtClass = expr->getStmtClass(); 122 d_.Report(clang::FullSourceLoc(expr->getExprLoc(), sm_), 123 d_.getCustomDiagID(clang::DiagnosticsEngine::Remark, "%0")) << stmtClass; 124 } 125 126For instance, gcmole currently doesn't support AtomicExprClass statements 127introduced for atomic operations. 128 129A convenient way to observe the AST generated by Clang is to pass the following 130flags when invoking clang++ 131 132 -Xclang -ast-dump -fsyntax-only 133