1Turbolizer
2==========
3
4Turbolizer is a HTML-based tool that visualizes optimized code along the various
5phases of Turbofan's optimization pipeline, allowing easy navigation between
6source code, Turbofan IR graphs, scheduled IR nodes and generated assembly code.
7
8Turbolizer consumes .json files that are generated per-function by d8 by passing
9the '--trace-turbo' command-line flag.
10
11Host the turbolizer locally by starting a web server that serves the contents of
12the turbolizer directory, e.g.:
13
14    cd src/tools/turbolizer
15    python -m SimpleHTTPServer 8000
16
17Optionally, profiling data generated by the perf tools in linux can be merged
18with the .json files using the turbolizer-perf.py file included. The following
19command is an example of using the perf script:
20
21    perf script -i perf.data.jitted -s turbolizer-perf.py turbo-main.json
22
23The output of the above command is a json object that can be piped to a file
24which, when uploaded to turbolizer, will display the event counts from perf next
25to each instruction in the disassembly. Further detail can be found in the
26bottom of this document under "Using Perf with Turbo."
27
28Using the python interface in perf script requires python-dev to be installed
29and perf be recompiled with python support enabled. Once recompiled, the
30variable PERF_EXEC_PATH must be set to the location of the recompiled perf
31binaries.
32
33Graph visualization and manipulation based on Mike Bostock's sample code for an
34interactive tool for creating directed graphs. Original source is at
35https://github.com/metacademy/directed-graph-creator and released under the
36MIT/X license.
37
38Icons derived from the "White Olive Collection" created by Breezi released under
39the Creative Commons BY license.
40
41Using Perf with Turbo
42---------------------
43
44In order to generate perf data that matches exactly with the turbofan trace, you
45must use either a debug build of v8 or a release build with the flag
46'disassembler=on'. This flag ensures that the '--trace-turbo' will output the
47necessary disassembly for linking with the perf profile.
48
49The basic example of generating the required data is as follows:
50
51    perf record -k mono /path/to/d8 --turbo --trace-turbo --perf-prof main.js
52    perf inject -j -i perf.data -o perf.data.jitted
53    perf script -i perf.data.jitted -s turbolizer-perf.py turbo-main.json
54
55These commands combined will run and profile d8, merge the output into a single
56'perf.data.jitted' file, then take the event data from that and link them to the
57disassembly in the 'turbo-main.json'. Note that, as above, the output of the
58script command must be piped to a file for uploading to turbolizer.
59
60There are many options that can be added to the first command, for example '-e'
61can be used to specify the counting of specific events (default: cycles), as
62well as '--cpu' to specify which CPU to sample.