README.md 3.34 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
Turbolizer
==========

Turbolizer is a HTML-based tool that visualizes optimized code along the various
phases of Turbofan's optimization pipeline, allowing easy navigation between
source code, Turbofan IR graphs, scheduled IR nodes and generated assembly code.

Turbolizer consumes .json files that are generated per-function by d8 by passing
the '--trace-turbo' command-line flag.

11 12
Turbolizer is build using npm:

13
    cd tools/turbolizer
14 15
    npm i
    npm run-script build
16 17 18

Afterwards, turbolizer can be hosted locally by starting a web server that serve
the contents of the turbolizer directory, e.g.:
19 20 21

    python -m SimpleHTTPServer 8000

22 23 24 25 26
To deploy to a directory that can be hosted the script `deploy` can be used. The
following command will deploy to the directory /www/turbolizer:

    npm run deploy -- /www/turbolizer

27
Optionally, profiling data generated by the perf tools in linux can be merged
28
with the .json files using the turbolizer-perf.py file included. The following
29 30
command is an example of using the perf script:

31
    perf script -i perf.data.jitted -s turbolizer-perf.py turbo-main.json
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60

The output of the above command is a json object that can be piped to a file
which, when uploaded to turbolizer, will display the event counts from perf next
to each instruction in the disassembly. Further detail can be found in the
bottom of this document under "Using Perf with Turbo."

Using the python interface in perf script requires python-dev to be installed
and perf be recompiled with python support enabled. Once recompiled, the
variable PERF_EXEC_PATH must be set to the location of the recompiled perf
binaries.

Graph visualization and manipulation based on Mike Bostock's sample code for an
interactive tool for creating directed graphs. Original source is at
https://github.com/metacademy/directed-graph-creator and released under the
MIT/X license.

Icons derived from the "White Olive Collection" created by Breezi released under
the Creative Commons BY license.

Using Perf with Turbo
---------------------

In order to generate perf data that matches exactly with the turbofan trace, you
must use either a debug build of v8 or a release build with the flag
'disassembler=on'. This flag ensures that the '--trace-turbo' will output the
necessary disassembly for linking with the perf profile.

The basic example of generating the required data is as follows:

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 65 66 67 68 69 70 71

These commands combined will run and profile d8, merge the output into a single
'perf.data.jitted' file, then take the event data from that and link them to the
disassembly in the 'turbo-main.json'. Note that, as above, the output of the
script command must be piped to a file for uploading to turbolizer.

There are many options that can be added to the first command, for example '-e'
can be used to specify the counting of specific events (default: cycles), as
72
well as '--cpu' to specify which CPU to sample.
73 74 75 76 77 78 79 80

Turbolizer build process
------------------------

Turbolizer is currently migrating to TypeScript. The typescript sources reside in
tools/turbolizer/src, and the typescript compiler will put the JavaScript output
into tools/turbolizer/build/. The index.html file is set up to load the JavaScript
from that directory.