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
11Turbolizer is build using npm:
12
13    cd tools/turbolizer
14    npm i
15    npm run-script build
16
17Afterwards, turbolizer can be hosted locally by starting a web server that serve
18the contents of the turbolizer directory, e.g.:
19
20    python -m SimpleHTTPServer 8000
21
22To deploy to a directory that can be hosted the script `deploy` can be used. The
23following command will deploy to the directory /www/turbolizer:
24
25    npm run deploy -- /www/turbolizer
26
27Optionally, profiling data generated by the perf tools in linux can be merged
28with the .json files using the turbolizer-perf.py file included. The following
29command is an example of using the perf script:
30
31    perf script -i perf.data.jitted -s turbolizer-perf.py turbo-main.json
32
33The output of the above command is a json object that can be piped to a file
34which, when uploaded to turbolizer, will display the event counts from perf next
35to each instruction in the disassembly. Further detail can be found in the
36bottom of this document under "Using Perf with Turbo."
37
38Using the python interface in perf script requires python-dev to be installed
39and perf be recompiled with python support enabled. Once recompiled, the
40variable PERF_EXEC_PATH must be set to the location of the recompiled perf
41binaries.
42
43Graph visualization and manipulation based on Mike Bostock's sample code for an
44interactive tool for creating directed graphs. Original source is at
45https://github.com/metacademy/directed-graph-creator and released under the
46MIT/X license.
47
48Icons derived from the "White Olive Collection" created by Breezi released under
49the Creative Commons BY license.
50
51Using Perf with Turbo
52---------------------
53
54In order to generate perf data that matches exactly with the turbofan trace, you
55must use either a debug build of v8 or a release build with the flag
56'disassembler=on'. This flag ensures that the '--trace-turbo' will output the
57necessary disassembly for linking with the perf profile.
58
59The basic example of generating the required data is as follows:
60
61    perf record -k mono /path/to/d8 --trace-turbo --perf-prof main.js
62    perf inject -j -i perf.data -o perf.data.jitted
63    perf script -i perf.data.jitted -s turbolizer-perf.py turbo-main.json
64
65These commands combined will run and profile d8, merge the output into a single
66'perf.data.jitted' file, then take the event data from that and link them to the
67disassembly in the 'turbo-main.json'. Note that, as above, the output of the
68script command must be piped to a file for uploading to turbolizer.
69
70There are many options that can be added to the first command, for example '-e'
71can be used to specify the counting of specific events (default: cycles), as
72well as '--cpu' to specify which CPU to sample.
73
74Turbolizer build process
75------------------------
76
77The typescript sources reside in tools/turbolizer/src, and the typescript
78compiler will put the JavaScript output into tools/turbolizer/build/. The
79index.html file is set up to load the JavaScript from that directory.
80