television/docs/UserGuide.html - llvm-archive - Git at Google

 <html>
 <head>
   <title>LLVM Visualization Tool User Guide</title>
 </head>
 <body>

 <h2><img src="images/llvmtv-logo.png" alt="[LLVM-TV Logo]">LLVM Visualization Tool User Guide</h2>

 <h3><u>Required Software:</u></h3>
 In order to compile and run the LLVM Visualization Tool (LLVM-TV), the following software
 must be installed:

 <ul>
 <li><b>The Low Level Virtual Machine (LLVM) Compiler Infrastructure:</b> You
 must check out the latest version from CVS. LLVM-TV does not work with
 LLVM version 1.2, the latest released version at the time of this writing.
 See the <a href="http://llvm.cs.uiuc.edu/docs/GettingStarted.html">LLVM Getting
 Started Guide</a> for details.</li>
 <li><b>Dot</b>: Included in the AT&T Research <a href="http://www.research.att.com/sw/tools/graphviz/">Graphviz</a> package, LLVM-TV uses Dot to draw directed
 graphs. For best results, make sure you have TrueType fonts installed.</li>
 </ul>
 <p>

 <h3><u>Download:</u></h3>
 <p>Once you have unpacked and compiled LLVM, download the LLVM Visualization
 Tool sources and unpack them in the <tt>projects</tt> subdirectory of your LLVM
 source tree.</p>
 <pre>
     % cd llvm/projects
     % tar xzvf llvm-tv.tgz
     % cd llvm-tv
 </pre>

 <p>

 <h3><u>Compiling:</u></h3>
 <p>You must then compile the LLVM Visualization Tool.</p>
 <pre>
     % ./configure --with-llvmsrc=[path] --with-llvmobj=[path]
 </pre>
 <p><i>If you're building in llvm/projects/llvm-tv, then you don't need
    to specify these --with options.</i></p>
 <pre>
     % cd lib/wxwindows
     % ./configure --enable-debug --prefix=`pwd`
 </pre>
 <p><i>Make absolutely sure that wxWindows's configure script detects the same
    C++ compiler that you used to compile LLVM. Otherwise, you may get
    weird link errors when trying to link the llvm-tv tool.</i></p>
 <pre>
     % cd ../..
     % gmake
 </pre>

 <p>

 <h3><u>Using the LLVM Visualization Tool:</u></h3>

 The main purpose of the LLVM Visualization tool is to view the effects of transformations written in the LLVM framework. We call the points in time after a transformation has been run "snapshots." <p>

 Note: opt-snap and llvm-tv.exe may be found in the tools/Debug directory.
 <p>

 <h4>Acquiring a Snapshot:</h4>

 <p>Using the LLVM tool 'opt', one runs transformations on an LLVM Bytecode file.
 Please see the <a href="http://llvm.cs.uiuc.edu/docs/CommandGuide/opt.html">man
 page</a> on opt for details on what transformations are available.</p>

 <p>In order to acquire snapshots after a transformation or a series of
 transformations have been applied, you use the 'opt-snap' tool. You simply place
 the option '-snapshot' after specifying your transformation options. You may ask
 for a snapshot any number of times.</p>

 <p>Here is an example of using opt to acquire snapshots. We will run two
 optimizations (loop-invariant code motion and global common-subexpression
 elimination) on the program whose LLVM bytecode is in the file
 <tt>bytecode-file.bc</tt>, and take a snapshot after each pass completes:</p>
 <pre>
     % opt-snap -debug -licm -snapshot -gcse -snapshot < bytecode-file.bc > /dev/null
 </pre>

 <p>All snapshots are placed in the directory
 <tt>/tmp/llvm-tv-<i>username</i>/snapshots</tt>, where <tt><i>username</i></tt>
 is your login name.</p>

 <h4>Viewing a Snapshot:</h4>
 <p>Begin by starting up the LLVM Visualization tool GUI. Make sure llvm-tv.exe
 is in your PATH, then type:</p>

 <pre>
     % llvm-tv.exe
 </pre>

 <p>This should pop up a window such as the following:</p>
 <img src="images/llvmtv-firstopen.jpg"><p>

 <p>Notice that all the snapshots are listed in the tree view structure on the left
 side of the frame. Compilation units in LLVM have a simple, hierarchical
 structure:
 a Module contains Functions, which contain BasicBlocks, which contain
 Instructions. The tree view will show you functions within the snapshot you are viewing.</p>

 <p>
 From this screen shot, you can see that we have expanded a module revealing that it has several functions within it.</p>
 <img src="images/llvmtv-expandmodule.jpg">

 <p>
 To the right of the tree view is a tabbed pane that allows you to easily browse
 different views of the snapshot.</p>

 <b>TextView:</b><br>

 <p>The text view is a direct disassembly of the Module, showing the pointer size
 of the target architecture for which it was compiled, endianness, the
 user-defined types present in the module, global variables, and all function
 definitions.</p>

 <img src="images/llvmtv-TextView.jpg"><p>

 <b>HTMLView:</b><br>

 <p>The HTML view is a syntax-highlighted view with LLVM keywords in blue, types
 in green, and BasicBlock names in red. For brevity, the Module view does not
 include the types and the functions are given as prototypes. External functions,
 for which the Module has no code, are prepended with a `declare' keyword. Other
 functions' code can be viewed by clicking on the appropriate node in the tree
 list.</p>

 <img src="images/llvmtv-HTMLView.jpg"><p>


 <b>DSGraph Views:</b><br>

 <p>LLVM has a powerful alias analysis framework and here we are showcasing its
 novel Data Structure Analysis (DSA) algorithm. It has 3 components: the
 Bottom-Up DSGraph, Top-down DSGraph, and Local DSGraph. These graphs show
 points-to results analysis for global variables and other pointers in a
 program. Here we see the results of a local data-structure analysis run:</p>

 <img src="images/llvmtv-LocalDSGraph.jpg"><p>

 <b>CodeView:</b><br>

 <p>Because LLVM is in SSA (Static Single Assignment) form, any use of a variable must
 be preceded by exactly one definition. We can thus form def-use chains which
 connect definitions of variables to their uses.  The CodeView enables one to
 click on any value and see where the uses of the variable occur, allowing a
 visual way to inspect code. As a side effect, clicking on a BasicBlock entry
 shows all users of the BasicBlock, which are branches that have the BasicBlock
 as a target, thus showing how many incoming control-flow edges a block has.</p>

 <img src="images/llvmtv-CodeView.jpg"><p>

 <p>There are also more views under the View menu. Selecting one of these views will
 open up a new window with that view in it. There are two new views that we have
 not seen before: Call Graph view and Control Flow Graph view.</p>

 <img src="images/llvmtv-ViewMenu.jpg"><p>

 <b>Call Graph:</b><br>

 <p>The Call Graph shows the callers and callees of each function in the module. A graph of
 functions, here each node represents a function and an arrow from node A to node
 B means that function A calls function B at least once in its code.</p>

 <b>Control Flow Graph:</b><br>

 <p>The control flow graph displays graphically the control flow of the function,
 identifying each basic block as a node and labeling all branches between blocks
 as arrows.</p>

 <img src="images/llvmtv-ControlFlow.jpg"><p>

 Additionally, you can use the File menu to add more snapshots to the visualizer.
 <br>
 <img src="images/llvmtv-FileMenu.jpg"><p>

 <b>Add Module:</b><br>

 <p>This will add a given Module to the list of snapshots without having to run
 opt-snap to deposit it into the snapshot collection. This is useful if you
 want to compare different programs, instead of looking at multiple views
 of the same program.</p>

 <b>Refresh:</b><br>

 <p>This option will re-read the snapshot collection directory to see if any new
 Modules have been added manually by the user (by copying directly through the
 filesystem).</p>

 <h4>Snapshots and Signaling:</h4>

 <p>
 A neat feature of the LLVM Visualization tool is that the GUI will automatically
 refresh the snapshot listing when opt-snap signals that a new snapshot has been
 generated. This is primarily useful for long-running optimizations.
 </p>

 </body>
 </html>
	<html>
	<head>
	<title>LLVM Visualization Tool User Guide</title>
	</head>
	<body>

	<h2><img src="images/llvmtv-logo.png" alt="[LLVM-TV Logo]">LLVM Visualization Tool User Guide</h2>

	<h3><u>Required Software:</u></h3>
	In order to compile and run the LLVM Visualization Tool (LLVM-TV), the following software
	must be installed:

	<ul>
	<li><b>The Low Level Virtual Machine (LLVM) Compiler Infrastructure:</b> You
	must check out the latest version from CVS. LLVM-TV does not work with
	LLVM version 1.2, the latest released version at the time of this writing.
	See the <a href="http://llvm.cs.uiuc.edu/docs/GettingStarted.html">LLVM Getting
	Started Guide</a> for details.</li>
	<li><b>Dot</b>: Included in the AT&T Research <a href="http://www.research.att.com/sw/tools/graphviz/">Graphviz</a> package, LLVM-TV uses Dot to draw directed
	graphs. For best results, make sure you have TrueType fonts installed.</li>
	</ul>
	<p>

	<h3><u>Download:</u></h3>
	<p>Once you have unpacked and compiled LLVM, download the LLVM Visualization
	Tool sources and unpack them in the <tt>projects</tt> subdirectory of your LLVM
	source tree.</p>
	<pre>
	% cd llvm/projects
	% tar xzvf llvm-tv.tgz
	% cd llvm-tv
	</pre>

	<p>

	<h3><u>Compiling:</u></h3>
	<p>You must then compile the LLVM Visualization Tool.</p>
	<pre>
	% ./configure --with-llvmsrc=[path] --with-llvmobj=[path]
	</pre>
	<p><i>If you're building in llvm/projects/llvm-tv, then you don't need
	to specify these --with options.</i></p>
	<pre>
	% cd lib/wxwindows
	% ./configure --enable-debug --prefix=`pwd`
	</pre>
	<p><i>Make absolutely sure that wxWindows's configure script detects the same
	C++ compiler that you used to compile LLVM. Otherwise, you may get
	weird link errors when trying to link the llvm-tv tool.</i></p>
	<pre>
	% cd ../..
	% gmake
	</pre>

	<p>

	<h3><u>Using the LLVM Visualization Tool:</u></h3>

	The main purpose of the LLVM Visualization tool is to view the effects of transformations written in the LLVM framework. We call the points in time after a transformation has been run "snapshots." <p>

	Note: opt-snap and llvm-tv.exe may be found in the tools/Debug directory.
	<p>

	<h4>Acquiring a Snapshot:</h4>

	<p>Using the LLVM tool 'opt', one runs transformations on an LLVM Bytecode file.
	Please see the <a href="http://llvm.cs.uiuc.edu/docs/CommandGuide/opt.html">man
	page</a> on opt for details on what transformations are available.</p>

	<p>In order to acquire snapshots after a transformation or a series of
	transformations have been applied, you use the 'opt-snap' tool. You simply place
	the option '-snapshot' after specifying your transformation options. You may ask
	for a snapshot any number of times.</p>

	<p>Here is an example of using opt to acquire snapshots. We will run two
	optimizations (loop-invariant code motion and global common-subexpression
	elimination) on the program whose LLVM bytecode is in the file
	<tt>bytecode-file.bc</tt>, and take a snapshot after each pass completes:</p>
	<pre>
	% opt-snap -debug -licm -snapshot -gcse -snapshot < bytecode-file.bc > /dev/null
	</pre>

	<p>All snapshots are placed in the directory
	<tt>/tmp/llvm-tv-<i>username</i>/snapshots</tt>, where <tt><i>username</i></tt>
	is your login name.</p>

	<h4>Viewing a Snapshot:</h4>
	<p>Begin by starting up the LLVM Visualization tool GUI. Make sure llvm-tv.exe
	is in your PATH, then type:</p>

	<pre>
	% llvm-tv.exe
	</pre>

	<p>This should pop up a window such as the following:</p>
	<img src="images/llvmtv-firstopen.jpg"><p>

	<p>Notice that all the snapshots are listed in the tree view structure on the left
	side of the frame. Compilation units in LLVM have a simple, hierarchical
	structure:
	a Module contains Functions, which contain BasicBlocks, which contain
	Instructions. The tree view will show you functions within the snapshot you are viewing.</p>

	<p>
	From this screen shot, you can see that we have expanded a module revealing that it has several functions within it.</p>
	<img src="images/llvmtv-expandmodule.jpg">

	<p>
	To the right of the tree view is a tabbed pane that allows you to easily browse
	different views of the snapshot.</p>

	<b>TextView:</b><br>

	<p>The text view is a direct disassembly of the Module, showing the pointer size
	of the target architecture for which it was compiled, endianness, the
	user-defined types present in the module, global variables, and all function
	definitions.</p>

	<img src="images/llvmtv-TextView.jpg"><p>

	<b>HTMLView:</b><br>

	<p>The HTML view is a syntax-highlighted view with LLVM keywords in blue, types
	in green, and BasicBlock names in red. For brevity, the Module view does not
	include the types and the functions are given as prototypes. External functions,
	for which the Module has no code, are prepended with a `declare' keyword. Other
	functions' code can be viewed by clicking on the appropriate node in the tree
	list.</p>

	<img src="images/llvmtv-HTMLView.jpg"><p>


	<b>DSGraph Views:</b><br>

	<p>LLVM has a powerful alias analysis framework and here we are showcasing its
	novel Data Structure Analysis (DSA) algorithm. It has 3 components: the
	Bottom-Up DSGraph, Top-down DSGraph, and Local DSGraph. These graphs show
	points-to results analysis for global variables and other pointers in a
	program. Here we see the results of a local data-structure analysis run:</p>

	<img src="images/llvmtv-LocalDSGraph.jpg"><p>

	<b>CodeView:</b><br>

	<p>Because LLVM is in SSA (Static Single Assignment) form, any use of a variable must
	be preceded by exactly one definition. We can thus form def-use chains which
	connect definitions of variables to their uses. The CodeView enables one to
	click on any value and see where the uses of the variable occur, allowing a
	visual way to inspect code. As a side effect, clicking on a BasicBlock entry
	shows all users of the BasicBlock, which are branches that have the BasicBlock
	as a target, thus showing how many incoming control-flow edges a block has.</p>

	<img src="images/llvmtv-CodeView.jpg"><p>

	<p>There are also more views under the View menu. Selecting one of these views will
	open up a new window with that view in it. There are two new views that we have
	not seen before: Call Graph view and Control Flow Graph view.</p>

	<img src="images/llvmtv-ViewMenu.jpg"><p>

	<b>Call Graph:</b><br>

	<p>The Call Graph shows the callers and callees of each function in the module. A graph of
	functions, here each node represents a function and an arrow from node A to node
	B means that function A calls function B at least once in its code.</p>

	<b>Control Flow Graph:</b><br>

	<p>The control flow graph displays graphically the control flow of the function,
	identifying each basic block as a node and labeling all branches between blocks
	as arrows.</p>

	<img src="images/llvmtv-ControlFlow.jpg"><p>

	Additionally, you can use the File menu to add more snapshots to the visualizer.
	<br>
	<img src="images/llvmtv-FileMenu.jpg"><p>

	<b>Add Module:</b><br>

	<p>This will add a given Module to the list of snapshots without having to run
	opt-snap to deposit it into the snapshot collection. This is useful if you
	want to compare different programs, instead of looking at multiple views
	of the same program.</p>

	<b>Refresh:</b><br>

	<p>This option will re-read the snapshot collection directory to see if any new
	Modules have been added manually by the user (by copying directly through the
	filesystem).</p>

	<h4>Snapshots and Signaling:</h4>

	<p>
	A neat feature of the LLVM Visualization tool is that the GUI will automatically
	refresh the snapshot listing when opt-snap signals that a new snapshot has been
	generated. This is primarily useful for long-running optimizations.
	</p>

	</body>
	</html>