README
1DESCRIPTION -------------------------------------------------------------------
2
3gcmole is a simple static analysis tool used to find possible evaluation order
4dependent GC-unsafe places in the V8 codebase.
5
6For example the following code is GC-unsafe:
7
8Handle<Object> Foo(); // Assume Foo can trigger a GC.
9void Bar(Object*, Object*);
10
11Handle<Object> baz;
12baz->Qux(*Foo()); // (a)
13Bar(*Foo(), *baz); // (b)
14
15Both in cases (a) and (b) compiler is free to evaluate call arguments (that
16includes receiver) in any order. That means it can dereference baz before
17calling to Foo and save a raw pointer to a heap object in the register or
18on the stack.
19
20PREREQUISITES -----------------------------------------------------------------
21
221) Install Lua 5.1
23
242) Get LLVM and Clang sources and build them.
25
26Follow the instructions on http://clang.llvm.org/get_started.html.
27
28Make sure to pass --enable-optimized to configure to get Release build
29instead of a Debug one.
30
313) Build gcmole Clang plugin (libgcmole.so)
32
33In the tools/gcmole execute the following command:
34
35LLVM_SRC_ROOT=<path-to-llvm-source-root> make
36
37USING GCMOLE ------------------------------------------------------------------
38
39gcmole consists of driver script written in Lua and Clang plugin that does
40C++ AST processing. Plugin (libgcmole.so) is expected to be in the same
41folder as driver (gcmole.lua).
42
43To start analysis cd into the root of v8 checkout and execute the following
44command:
45
46CLANG_BIN=<path-to-clang-bin-folder> lua tools/gcmole/gcmole.lua [<arch>]
47
48where arch should be one of architectures supported by V8 (arm, ia32, x64).
49
50Analysis will be performed in 2 stages:
51
52- on the first stage driver will parse all files and build a global callgraph
53approximation to find all functions that might potentially cause GC, list
54of this functions will be written into gcsuspects file.
55
56- on the second stage driver will parse all files again and will locate all
57callsites that might be GC-unsafe based on the list of functions causing GC.
58Such places are marked with a "Possible problem with evaluation order."
59warning. Messages "Failed to resolve v8::internal::Object" are benign and
60can be ignored.
61
62If any errors were found driver exits with non-zero status.
63