Blame - docs/Passes.rst - platform_external_llvm

blob: 81bd8acfc2dad49d4299528ab8a29a4638da0084 [file] [log] [blame]

Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	1	..
				2	If Passes.html is up to date, the following "one-liner" should print
				3	an empty diff.
				4
				5	egrep -e '^<tr><td><a href="#.">-.</a></td><td>.*</td></tr>$' \
				6	-e '^ <a name=".">.</a>$' < Passes.html >html; \
				7	perl >help <<'EOT' && diff -u help html; rm -f help html
				8	open HTML, "<Passes.html" or die "open: Passes.html: $!\n";
				9	while (<HTML>) {
				10	m:^<tr><td><a href="#(.)">-.</a></td><td>.*</td></tr>$: or next;
				11	$order{$1} = sprintf("%03d", 1 + int %order);
				12	}
				13	open HELP, "../Release/bin/opt -help\|" or die "open: opt -help: $!\n";
				14	while (<HELP>) {
				15	m:^ -([^ ]+) +- (.*)$: or next;
				16	my $o = $order{$1};
				17	$o = "000" unless defined $o;
				18	push @x, "$o<tr><td><a href=\"#$1\">-$1</a></td><td>$2</td></tr>\n";
				19	push @y, "$o <a name=\"$1\">-$1: $2</a>\n";
				20	}
				21	@x = map { s/^\d\d\d//; $_ } sort @x;
				22	@y = map { s/^\d\d\d//; $_ } sort @y;
				23	print @x, @y;
				24	EOT
				25
				26	This (real) one-liner can also be helpful when converting comments to HTML:
				27
				28	perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ ///? ?::; print " <p>\n" if !$on && $_ =~ /\S/; print " </p>\n" if $on && $_ =~ /^\s$/; print " $_\n"; $on = ($_ =~ /\S/); } print " </p>\n" if $on'
				29
				30	====================================
				31	LLVM's Analysis and Transform Passes
				32	====================================
				33
				34	.. contents::
				35	:local:
				36
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	37	Introduction
				38	============
				39
				40	This document serves as a high level summary of the optimization features that
				41	LLVM provides. Optimizations are implemented as Passes that traverse some
				42	portion of a program to either collect information or transform the program.
				43	The table below divides the passes that LLVM provides into three categories.
				44	Analysis passes compute information that other passes can use or for debugging
				45	or program visualization purposes. Transform passes can use (or invalidate)
				46	the analysis passes. Transform passes all mutate the program in some way.
				47	Utility passes provides some utility but don't otherwise fit categorization.
				48	For example passes to extract functions to bitcode or write a module to bitcode
				49	are neither analysis nor transform passes. The table of contents above
				50	provides a quick summary of each pass and links to the more complete pass
				51	description later in the document.
				52
				53	Analysis Passes
				54	===============
				55
				56	This section describes the LLVM Analysis Passes.
				57
				58	``-aa-eval``: Exhaustive Alias Analysis Precision Evaluator
				59	-----------------------------------------------------------
				60
				61	This is a simple N^2 alias analysis accuracy evaluator. Basically, for each
				62	function in the program, it simply queries to see how the alias analysis
				63	implementation answers alias queries between each pair of pointers in the
				64	function.
				65
				66	This is inspired and adapted from code by: Naveen Neelakantam, Francesco
				67	Spadini, and Wojciech Stryjewski.
				68
				69	``-basicaa``: Basic Alias Analysis (stateless AA impl)
				70	------------------------------------------------------
				71
				72	A basic alias analysis pass that implements identities (two different globals
				73	cannot alias, etc), but does no stateful analysis.
				74
				75	``-basiccg``: Basic CallGraph Construction
				76	------------------------------------------
				77
				78	Yet to be written.
				79
				80	``-count-aa``: Count Alias Analysis Query Responses
				81	---------------------------------------------------
				82
				83	A pass which can be used to count how many alias queries are being made and how
				84	the alias analysis implementation being used responds.
				85
David Green	9182393	2018-07-19 12:37:00 +0000	[diff] [blame]	86	.. _passes-da:
				87
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	88	``-da``: Dependence Analysis
				89	----------------------------
				90
				91	Dependence analysis framework, which is used to detect dependences in memory
				92	accesses.
				93
				94	``-debug-aa``: AA use debugger
				95	------------------------------
				96
				97	This simple pass checks alias analysis users to ensure that if they create a
				98	new value, they do not query AA without informing it of the value. It acts as
				99	a shim over any other AA pass you want.
				100
				101	Yes keeping track of every value in the program is expensive, but this is a
				102	debugging pass.
				103
				104	``-domfrontier``: Dominance Frontier Construction
				105	-------------------------------------------------
				106
				107	This pass is a simple dominator construction algorithm for finding forward
				108	dominator frontiers.
				109
				110	``-domtree``: Dominator Tree Construction
				111	-----------------------------------------
				112
				113	This pass is a simple dominator construction algorithm for finding forward
				114	dominators.
				115
				116
				117	``-dot-callgraph``: Print Call Graph to "dot" file
				118	--------------------------------------------------
				119
				120	This pass, only available in ``opt``, prints the call graph into a ``.dot``
				121	graph. This graph can then be processed with the "dot" tool to convert it to
				122	postscript or some other suitable format.
				123
				124	``-dot-cfg``: Print CFG of function to "dot" file
				125	-------------------------------------------------
				126
				127	This pass, only available in ``opt``, prints the control flow graph into a
				128	``.dot`` graph. This graph can then be processed with the :program:`dot` tool
				129	to convert it to postscript or some other suitable format.
				130
				131	``-dot-cfg-only``: Print CFG of function to "dot" file (with no function bodies)
				132	--------------------------------------------------------------------------------
				133
				134	This pass, only available in ``opt``, prints the control flow graph into a
				135	``.dot`` graph, omitting the function bodies. This graph can then be processed
				136	with the :program:`dot` tool to convert it to postscript or some other suitable
				137	format.
				138
				139	``-dot-dom``: Print dominance tree of function to "dot" file
				140	------------------------------------------------------------
				141
				142	This pass, only available in ``opt``, prints the dominator tree into a ``.dot``
				143	graph. This graph can then be processed with the :program:`dot` tool to
				144	convert it to postscript or some other suitable format.
				145
				146	``-dot-dom-only``: Print dominance tree of function to "dot" file (with no function bodies)
				147	-------------------------------------------------------------------------------------------
				148
				149	This pass, only available in ``opt``, prints the dominator tree into a ``.dot``
				150	graph, omitting the function bodies. This graph can then be processed with the
				151	:program:`dot` tool to convert it to postscript or some other suitable format.
				152
				153	``-dot-postdom``: Print postdominance tree of function to "dot" file
				154	--------------------------------------------------------------------
				155
				156	This pass, only available in ``opt``, prints the post dominator tree into a
				157	``.dot`` graph. This graph can then be processed with the :program:`dot` tool
				158	to convert it to postscript or some other suitable format.
				159
				160	``-dot-postdom-only``: Print postdominance tree of function to "dot" file (with no function bodies)
				161	---------------------------------------------------------------------------------------------------
				162
				163	This pass, only available in ``opt``, prints the post dominator tree into a
				164	``.dot`` graph, omitting the function bodies. This graph can then be processed
				165	with the :program:`dot` tool to convert it to postscript or some other suitable
				166	format.
				167
				168	``-globalsmodref-aa``: Simple mod/ref analysis for globals
				169	----------------------------------------------------------
				170
				171	This simple pass provides alias and mod/ref information for global values that
				172	do not have their address taken, and keeps track of whether functions read or
				173	write memory (are "pure"). For this simple (but very common) case, we can
				174	provide pretty accurate and useful information.
				175
				176	``-instcount``: Counts the various types of ``Instruction``\ s
				177	--------------------------------------------------------------
				178
				179	This pass collects the count of all instructions and reports them.
				180
				181	``-intervals``: Interval Partition Construction
				182	-----------------------------------------------
				183
				184	This analysis calculates and represents the interval partition of a function,
				185	or a preexisting interval partition.
				186
				187	In this way, the interval partition may be used to reduce a flow graph down to
				188	its degenerate single node interval partition (unless it is irreducible).
				189
				190	``-iv-users``: Induction Variable Users
				191	---------------------------------------
				192
				193	Bookkeeping for "interesting" users of expressions computed from induction
				194	variables.
				195
				196	``-lazy-value-info``: Lazy Value Information Analysis
				197	-----------------------------------------------------
				198
				199	Interface for lazy computation of value constraint information.
				200
				201	``-libcall-aa``: LibCall Alias Analysis
				202	---------------------------------------
				203
				204	LibCall Alias Analysis.
				205
				206	``-lint``: Statically lint-checks LLVM IR
				207	-----------------------------------------
				208
				209	This pass statically checks for common and easily-identified constructs which
				210	produce undefined or likely unintended behavior in LLVM IR.
				211
				212	It is not a guarantee of correctness, in two ways. First, it isn't
				213	comprehensive. There are checks which could be done statically which are not
				214	yet implemented. Some of these are indicated by TODO comments, but those
				215	aren't comprehensive either. Second, many conditions cannot be checked
				216	statically. This pass does no dynamic instrumentation, so it can't check for
				217	all possible problems.
				218
				219	Another limitation is that it assumes all code will be executed. A store
				220	through a null pointer in a basic block which is never reached is harmless, but
				221	this pass will warn about it anyway.
				222
				223	Optimization passes may make conditions that this pass checks for more or less
				224	obvious. If an optimization pass appears to be introducing a warning, it may
				225	be that the optimization pass is merely exposing an existing condition in the
				226	code.
				227
				228	This code may be run before :ref:`instcombine <passes-instcombine>`. In many
				229	cases, instcombine checks for the same kinds of things and turns instructions
				230	with undefined behavior into unreachable (or equivalent). Because of this,
				231	this pass makes some effort to look through bitcasts and so on.
				232
				233	``-loops``: Natural Loop Information
				234	------------------------------------
				235
				236	This analysis is used to identify natural loops and determine the loop depth of
				237	various nodes of the CFG. Note that the loops identified may actually be
				238	several natural loops that share the same header node... not just a single
				239	natural loop.
				240
				241	``-memdep``: Memory Dependence Analysis
				242	---------------------------------------
				243
				244	An analysis that determines, for a given memory operation, what preceding
				245	memory operations it depends on. It builds on alias analysis information, and
				246	tries to provide a lazy, caching interface to a common kind of alias
				247	information query.
				248
				249	``-module-debuginfo``: Decodes module-level debug info
				250	------------------------------------------------------
				251
				252	This pass decodes the debug info metadata in a module and prints in a
				253	(sufficiently-prepared-) human-readable form.
				254
				255	For example, run this pass from ``opt`` along with the ``-analyze`` option, and
				256	it'll print to standard output.
				257
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	258	``-postdomfrontier``: Post-Dominance Frontier Construction
				259	----------------------------------------------------------
				260
				261	This pass is a simple post-dominator construction algorithm for finding
				262	post-dominator frontiers.
				263
				264	``-postdomtree``: Post-Dominator Tree Construction
				265	--------------------------------------------------
				266
				267	This pass is a simple post-dominator construction algorithm for finding
				268	post-dominators.
				269
				270	``-print-alias-sets``: Alias Set Printer
				271	----------------------------------------
				272
				273	Yet to be written.
				274
				275	``-print-callgraph``: Print a call graph
				276	----------------------------------------
				277
				278	This pass, only available in ``opt``, prints the call graph to standard error
				279	in a human-readable form.
				280
				281	``-print-callgraph-sccs``: Print SCCs of the Call Graph
				282	-------------------------------------------------------
				283
				284	This pass, only available in ``opt``, prints the SCCs of the call graph to
				285	standard error in a human-readable form.
				286
				287	``-print-cfg-sccs``: Print SCCs of each function CFG
				288	----------------------------------------------------
				289
				290	This pass, only available in ``opt``, printsthe SCCs of each function CFG to
				291	standard error in a human-readable fom.
				292
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	293	``-print-dom-info``: Dominator Info Printer
				294	-------------------------------------------
				295
				296	Dominator Info Printer.
				297
				298	``-print-externalfnconstants``: Print external fn callsites passed constants
				299	----------------------------------------------------------------------------
				300
				301	This pass, only available in ``opt``, prints out call sites to external
				302	functions that are called with constant arguments. This can be useful when
				303	looking for standard library functions we should constant fold or handle in
				304	alias analyses.
				305
				306	``-print-function``: Print function to stderr
				307	---------------------------------------------
				308
				309	The ``PrintFunctionPass`` class is designed to be pipelined with other
				310	``FunctionPasses``, and prints out the functions of the module as they are
				311	processed.
				312
				313	``-print-module``: Print module to stderr
				314	-----------------------------------------
				315
				316	This pass simply prints out the entire module when it is executed.
				317
				318	.. _passes-print-used-types:
				319
				320	``-print-used-types``: Find Used Types
				321	--------------------------------------
				322
				323	This pass is used to seek out all of the types in use by the program. Note
				324	that this analysis explicitly does not include types only used by the symbol
				325	table.
				326
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	327	``-regions``: Detect single entry single exit regions
				328	-----------------------------------------------------
				329
				330	The ``RegionInfo`` pass detects single entry single exit regions in a function,
				331	where a region is defined as any subgraph that is connected to the remaining
				332	graph at only two spots. Furthermore, an hierarchical region tree is built.
				333
				334	``-scalar-evolution``: Scalar Evolution Analysis
				335	------------------------------------------------
				336
				337	The ``ScalarEvolution`` analysis can be used to analyze and catagorize scalar
				338	expressions in loops. It specializes in recognizing general induction
				339	variables, representing them with the abstract and opaque ``SCEV`` class.
				340	Given this analysis, trip counts of loops and other important properties can be
				341	obtained.
				342
				343	This analysis is primarily useful for induction variable substitution and
				344	strength reduction.
				345
				346	``-scev-aa``: ScalarEvolution-based Alias Analysis
				347	--------------------------------------------------
				348
				349	Simple alias analysis implemented in terms of ``ScalarEvolution`` queries.
				350
				351	This differs from traditional loop dependence analysis in that it tests for
				352	dependencies within a single iteration of a loop, rather than dependencies
				353	between different iterations.
				354
				355	``ScalarEvolution`` has a more complete understanding of pointer arithmetic
				356	than ``BasicAliasAnalysis``' collection of ad-hoc analyses.
				357
Vitaly Buka	d305cea	2018-11-26 23:16:07 +0000	[diff] [blame]	358	``-stack-safety``: Stack Safety Analysis
				359	------------------------------------------------
				360
				361	The ``StackSafety`` analysis can be used to determine if stack allocated
				362	variables can be considered safe from memory access bugs.
				363
				364	This analysis' primary purpose is to be used by sanitizers to avoid unnecessary
				365	instrumentation of safe variables.
				366
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	367	``-targetdata``: Target Data Layout
				368	-----------------------------------
				369
				370	Provides other passes access to information on how the size and alignment
				371	required by the target ABI for various data types.
				372
				373	Transform Passes
				374	================
				375
				376	This section describes the LLVM Transform Passes.
				377
				378	``-adce``: Aggressive Dead Code Elimination
				379	-------------------------------------------
				380
				381	ADCE aggressively tries to eliminate code. This pass is similar to :ref:`DCE
				382	<passes-dce>` but it assumes that values are dead until proven otherwise. This
				383	is similar to :ref:`SCCP <passes-sccp>`, except applied to the liveness of
				384	values.
				385
				386	``-always-inline``: Inliner for ``always_inline`` functions
				387	-----------------------------------------------------------
				388
				389	A custom inliner that handles only functions that are marked as "always
				390	inline".
				391
				392	``-argpromotion``: Promote 'by reference' arguments to scalars
				393	--------------------------------------------------------------
				394
				395	This pass promotes "by reference" arguments to be "by value" arguments. In
				396	practice, this means looking for internal functions that have pointer
				397	arguments. If it can prove, through the use of alias analysis, that an
				398	argument is only loaded, then it can pass the value into the function instead
				399	of the address of the value. This can cause recursive simplification of code
				400	and lead to the elimination of allocas (especially in C++ template code like
				401	the STL).
				402
				403	This pass also handles aggregate arguments that are passed into a function,
				404	scalarizing them if the elements of the aggregate are only loaded. Note that
				405	it refuses to scalarize aggregates which would require passing in more than
				406	three operands to the function, because passing thousands of operands for a
				407	large array or structure is unprofitable!
				408
				409	Note that this transformation could also be done for arguments that are only
				410	stored to (returning the value instead), but does not currently. This case
				411	would be best handled when and if LLVM starts supporting multiple return values
				412	from functions.
				413
				414	``-bb-vectorize``: Basic-Block Vectorization
				415	--------------------------------------------
				416
				417	This pass combines instructions inside basic blocks to form vector
				418	instructions. It iterates over each basic block, attempting to pair compatible
				419	instructions, repeating this process until no additional pairs are selected for
				420	vectorization. When the outputs of some pair of compatible instructions are
				421	used as inputs by some other pair of compatible instructions, those pairs are
				422	part of a potential vectorization chain. Instruction pairs are only fused into
				423	vector instructions when they are part of a chain longer than some threshold
				424	length. Moreover, the pass attempts to find the best possible chain for each
				425	pair of compatible instructions. These heuristics are intended to prevent
				426	vectorization in cases where it would not yield a performance increase of the
				427	resulting code.
				428
				429	``-block-placement``: Profile Guided Basic Block Placement
				430	----------------------------------------------------------
				431
				432	This pass is a very simple profile guided basic block placement algorithm. The
				433	idea is to put frequently executed blocks together at the start of the function
				434	and hopefully increase the number of fall-through conditional branches. If
				435	there is no profile information for a particular function, this pass basically
				436	orders blocks in depth-first order.
				437
				438	``-break-crit-edges``: Break critical edges in CFG
				439	--------------------------------------------------
				440
				441	Break all of the critical edges in the CFG by inserting a dummy basic block.
				442	It may be "required" by passes that cannot deal with critical edges. This
				443	transformation obviously invalidates the CFG, but can update forward dominator
				444	(set, immediate dominators, tree, and frontier) information.
				445
				446	``-codegenprepare``: Optimize for code generation
				447	-------------------------------------------------
				448
				449	This pass munges the code in the input function to better prepare it for
Paul Robinson	5cb5ad9	2013-11-14 18:47:23 +0000	[diff] [blame]	450	SelectionDAG-based code generation. This works around limitations in its
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	451	basic-block-at-a-time approach. It should eventually be removed.
				452
				453	``-constmerge``: Merge Duplicate Global Constants
				454	-------------------------------------------------
				455
				456	Merges duplicate global constants together into a single constant that is
				457	shared. This is useful because some passes (i.e., TraceValues) insert a lot of
				458	string constants into the program, regardless of whether or not an existing
				459	string is available.
				460
				461	``-constprop``: Simple constant propagation
				462	-------------------------------------------
				463
Dmitri Gribenko	edc399a	2013-05-18 18:01:44 +0000	[diff] [blame]	464	This pass implements constant propagation and merging. It looks for
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	465	instructions involving only constant operands and replaces them with a constant
				466	value instead of an instruction. For example:
				467
				468	.. code-block:: llvm
				469
				470	add i32 1, 2
				471
				472	becomes
				473
				474	.. code-block:: llvm
				475
				476	i32 3
				477
				478	NOTE: this pass has a habit of making definitions be dead. It is a good idea
Dmitri Gribenko	edc399a	2013-05-18 18:01:44 +0000	[diff] [blame]	479	to run a :ref:`Dead Instruction Elimination <passes-die>` pass sometime after
				480	running this pass.
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	481
				482	.. _passes-dce:
				483
				484	``-dce``: Dead Code Elimination
				485	-------------------------------
				486
				487	Dead code elimination is similar to :ref:`dead instruction elimination
				488	<passes-die>`, but it rechecks instructions that were used by removed
				489	instructions to see if they are newly dead.
				490
				491	``-deadargelim``: Dead Argument Elimination
				492	-------------------------------------------
				493
				494	This pass deletes dead arguments from internal functions. Dead argument
				495	elimination removes arguments which are directly dead, as well as arguments
				496	only passed into function calls as dead arguments of other functions. This
				497	pass also deletes dead arguments in a similar way.
				498
				499	This pass is often useful as a cleanup pass to run after aggressive
				500	interprocedural passes, which add possibly-dead arguments.
				501
				502	``-deadtypeelim``: Dead Type Elimination
				503	----------------------------------------
				504
				505	This pass is used to cleanup the output of GCC. It eliminate names for types
				506	that are unused in the entire translation unit, using the :ref:`find used types
				507	<passes-print-used-types>` pass.
				508
				509	.. _passes-die:
				510
				511	``-die``: Dead Instruction Elimination
				512	--------------------------------------
				513
				514	Dead instruction elimination performs a single pass over the function, removing
				515	instructions that are obviously dead.
				516
				517	``-dse``: Dead Store Elimination
				518	--------------------------------
				519
				520	A trivial dead store elimination that only considers basic-block local
				521	redundant stores.
				522
Reid Kleckner	ed56048	2014-04-18 21:19:06 +0000	[diff] [blame]	523	.. _passes-functionattrs:
				524
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	525	``-functionattrs``: Deduce function attributes
				526	----------------------------------------------
				527
				528	A simple interprocedural pass which walks the call-graph, looking for functions
				529	which do not access or only read non-local memory, and marking them
				530	``readnone``/``readonly``. In addition, it marks function arguments (of
				531	pointer type) "``nocapture``" if a call to the function does not create any
				532	copies of the pointer value that outlive the call. This more or less means
				533	that the pointer is only dereferenced, and not returned from the function or
				534	stored in a global. This pass is implemented as a bottom-up traversal of the
				535	call-graph.
				536
				537	``-globaldce``: Dead Global Elimination
				538	---------------------------------------
				539
				540	This transform is designed to eliminate unreachable internal globals from the
				541	program. It uses an aggressive algorithm, searching out globals that are known
				542	to be alive. After it finds all of the globals which are needed, it deletes
				543	whatever is left over. This allows it to delete recursive chunks of the
				544	program which are unreachable.
				545
				546	``-globalopt``: Global Variable Optimizer
				547	-----------------------------------------
				548
				549	This pass transforms simple global variables that never have their address
				550	taken. If obviously true, it marks read/write globals as constant, deletes
				551	variables only stored to, etc.
				552
				553	``-gvn``: Global Value Numbering
				554	--------------------------------
				555
				556	This pass performs global value numbering to eliminate fully and partially
				557	redundant instructions. It also performs redundant load elimination.
				558
				559	.. _passes-indvars:
				560
				561	``-indvars``: Canonicalize Induction Variables
				562	----------------------------------------------
				563
				564	This transformation analyzes and transforms the induction variables (and
				565	computations derived from them) into simpler forms suitable for subsequent
				566	analysis and transformation.
				567
				568	This transformation makes the following changes to each loop with an
				569	identifiable induction variable:
				570
				571	* All loops are transformed to have a single canonical induction variable
				572	which starts at zero and steps by one.
				573	* The canonical induction variable is guaranteed to be the first PHI node in
				574	the loop header block.
				575	* Any pointer arithmetic recurrences are raised to use array subscripts.
				576
				577	If the trip count of a loop is computable, this pass also makes the following
				578	changes:
				579
				580	* The exit condition for the loop is canonicalized to compare the induction
				581	value against the exit value. This turns loops like:
				582
				583	.. code-block:: c++
				584
				585	for (i = 7; i*i < 1000; ++i)
				586
				587	into
				588
				589	.. code-block:: c++
				590
				591	for (i = 0; i != 25; ++i)
				592
				593	* Any use outside of the loop of an expression derived from the indvar is
				594	changed to compute the derived value outside of the loop, eliminating the
				595	dependence on the exit value of the induction variable. If the only purpose
				596	of the loop is to compute the exit value of some derived expression, this
				597	transformation will make the loop dead.
				598
				599	This transformation should be followed by strength reduction after all of the
				600	desired loop transformations have been performed. Additionally, on targets
				601	where it is profitable, the loop could be transformed to count down to zero
				602	(the "do loop" optimization).
				603
				604	``-inline``: Function Integration/Inlining
				605	------------------------------------------
				606
				607	Bottom-up inlining of functions into callees.
				608
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	609	.. _passes-instcombine:
				610
				611	``-instcombine``: Combine redundant instructions
				612	------------------------------------------------
				613
				614	Combine instructions to form fewer, simple instructions. This pass does not
Reid Kleckner	ed56048	2014-04-18 21:19:06 +0000	[diff] [blame]	615	modify the CFG. This pass is where algebraic simplification happens.
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	616
				617	This pass combines things like:
				618
				619	.. code-block:: llvm
				620
				621	%Y = add i32 %X, 1
				622	%Z = add i32 %Y, 1
				623
				624	into:
				625
				626	.. code-block:: llvm
				627
				628	%Z = add i32 %X, 2
				629
				630	This is a simple worklist driven algorithm.
				631
				632	This pass guarantees that the following canonicalizations are performed on the
				633	program:
				634
				635	#. If a binary operator has a constant operand, it is moved to the right-hand
				636	side.
				637	#. Bitwise operators with constant operands are always grouped so that shifts
				638	are performed first, then ``or``\ s, then ``and``\ s, then ``xor``\ s.
				639	#. Compare instructions are converted from ``<``, ``>``, ``≤``, or ``≥`` to
				640	``=`` or ``≠`` if possible.
				641	#. All ``cmp`` instructions on boolean values are replaced with logical
				642	operations.
				643	#. ``add X, X`` is represented as ``mul X, 2`` ⇒ ``shl X, 1``
				644	#. Multiplies with a constant power-of-two argument are transformed into
				645	shifts.
				646	#. … etc.
				647
Reid Kleckner	ed56048	2014-04-18 21:19:06 +0000	[diff] [blame]	648	This pass can also simplify calls to specific well-known function calls (e.g.
				649	runtime library functions). For example, a call ``exit(3)`` that occurs within
				650	the ``main()`` function can be transformed into simply ``return 3``. Whether or
				651	not library calls are simplified is controlled by the
				652	:ref:`-functionattrs <passes-functionattrs>` pass and LLVM's knowledge of
				653	library calls on different targets.
				654
Amjad Aboud	c6483fb	2018-01-25 12:06:32 +0000	[diff] [blame]	655	.. _passes-aggressive-instcombine:
				656
				657	``-aggressive-instcombine``: Combine expression patterns
				658	--------------------------------------------------------
				659
				660	Combine expression patterns to form expressions with fewer, simple instructions.
				661	This pass does not modify the CFG.
				662
				663	For example, this pass reduce width of expressions post-dominated by TruncInst
				664	into smaller width when applicable.
				665
				666	It differs from instcombine pass in that it contains pattern optimization that
				667	requires higher complexity than the O(1), thus, it should run fewer times than
				668	instcombine pass.
				669
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	670	``-internalize``: Internalize Global Symbols
				671	--------------------------------------------
				672
				673	This pass loops over all of the functions in the input module, looking for a
				674	main function. If a main function is found, all other functions and all global
				675	variables with initializers are marked as internal.
				676
				677	``-ipconstprop``: Interprocedural constant propagation
				678	------------------------------------------------------
				679
				680	This pass implements an extremely simple interprocedural constant propagation
				681	pass. It could certainly be improved in many different ways, like using a
				682	worklist. This pass makes arguments dead, but does not remove them. The
				683	existing dead argument elimination pass should be run after this to clean up
				684	the mess.
				685
				686	``-ipsccp``: Interprocedural Sparse Conditional Constant Propagation
				687	--------------------------------------------------------------------
				688
				689	An interprocedural variant of :ref:`Sparse Conditional Constant Propagation
				690	<passes-sccp>`.
				691
				692	``-jump-threading``: Jump Threading
				693	-----------------------------------
				694
				695	Jump threading tries to find distinct threads of control flow running through a
				696	basic block. This pass looks at blocks that have multiple predecessors and
				697	multiple successors. If one or more of the predecessors of the block can be
				698	proven to always cause a jump to one of the successors, we forward the edge
				699	from the predecessor to the successor by duplicating the contents of this
				700	block.
				701
				702	An example of when this can occur is code like this:
				703
				704	.. code-block:: c++
				705
				706	if () { ...
				707	X = 4;
				708	}
				709	if (X < 3) {
				710
				711	In this case, the unconditional branch at the end of the first if can be
				712	revectored to the false side of the second if.
				713
				714	``-lcssa``: Loop-Closed SSA Form Pass
				715	-------------------------------------
				716
				717	This pass transforms loops by placing phi nodes at the end of the loops for all
				718	values that are live across the loop boundary. For example, it turns the left
				719	into the right code:
				720
				721	.. code-block:: c++
				722
				723	for (...) for (...)
				724	if (c) if (c)
				725	X1 = ... X1 = ...
				726	else else
				727	X2 = ... X2 = ...
				728	X3 = phi(X1, X2) X3 = phi(X1, X2)
				729	... = X3 + 4 X4 = phi(X3)
				730	... = X4 + 4
				731
				732	This is still valid LLVM; the extra phi nodes are purely redundant, and will be
				733	trivially eliminated by ``InstCombine``. The major benefit of this
				734	transformation is that it makes many other loop optimizations, such as
				735	``LoopUnswitch``\ ing, simpler.
				736
				737	.. _passes-licm:
				738
				739	``-licm``: Loop Invariant Code Motion
				740	-------------------------------------
				741
				742	This pass performs loop invariant code motion, attempting to remove as much
				743	code from the body of a loop as possible. It does this by either hoisting code
				744	into the preheader block, or by sinking code to the exit blocks if it is safe.
				745	This pass also promotes must-aliased memory locations in the loop to live in
				746	registers, thus hoisting and sinking "invariant" loads and stores.
				747
				748	This pass uses alias analysis for two purposes:
				749
				750	#. Moving loop invariant loads and calls out of loops. If we can determine
				751	that a load or call inside of a loop never aliases anything stored to, we
				752	can hoist it or sink it like any other instruction.
				753
				754	#. Scalar Promotion of Memory. If there is a store instruction inside of the
				755	loop, we try to move the store to happen AFTER the loop instead of inside of
				756	the loop. This can only happen if a few conditions are true:
				757
				758	#. The pointer stored through is loop invariant.
				759	#. There are no stores or loads in the loop which may alias the pointer.
				760	There are no calls in the loop which mod/ref the pointer.
				761
				762	If these conditions are true, we can promote the loads and stores in the
				763	loop of the pointer to use a temporary alloca'd variable. We then use the
				764	:ref:`mem2reg <passes-mem2reg>` functionality to construct the appropriate
				765	SSA form for the variable.
				766
				767	``-loop-deletion``: Delete dead loops
				768	-------------------------------------
				769
				770	This file implements the Dead Loop Deletion Pass. This pass is responsible for
				771	eliminating loops with non-infinite computable trip counts that have no side
				772	effects or volatile instructions, and do not contribute to the computation of
				773	the function's return value.
				774
				775	.. _passes-loop-extract:
				776
				777	``-loop-extract``: Extract loops into new functions
				778	---------------------------------------------------
				779
				780	A pass wrapper around the ``ExtractLoop()`` scalar transformation to extract
				781	each top-level loop into its own new function. If the loop is the only loop
				782	in a given function, it is not touched. This is a pass most useful for
				783	debugging via bugpoint.
				784
				785	``-loop-extract-single``: Extract at most one loop into a new function
				786	----------------------------------------------------------------------
				787
				788	Similar to :ref:`Extract loops into new functions <passes-loop-extract>`, this
				789	pass extracts one natural loop from the program into a function if it can.
				790	This is used by :program:`bugpoint`.
				791
				792	``-loop-reduce``: Loop Strength Reduction
				793	-----------------------------------------
				794
				795	This pass performs a strength reduction on array references inside loops that
				796	have as one or more of their components the loop induction variable. This is
				797	accomplished by creating a new value to hold the initial value of the array
				798	access for the first iteration, and then creating a new GEP instruction in the
				799	loop to increment the value by the appropriate amount.
				800
				801	``-loop-rotate``: Rotate Loops
				802	------------------------------
				803
				804	A simple loop rotation transformation.
				805
				806	``-loop-simplify``: Canonicalize natural loops
				807	----------------------------------------------
				808
				809	This pass performs several transformations to transform natural loops into a
				810	simpler form, which makes subsequent analyses and transformations simpler and
				811	more effective.
				812
				813	Loop pre-header insertion guarantees that there is a single, non-critical entry
				814	edge from outside of the loop to the loop header. This simplifies a number of
				815	analyses and transformations, such as :ref:`LICM <passes-licm>`.
				816
				817	Loop exit-block insertion guarantees that all exit blocks from the loop (blocks
				818	which are outside of the loop that have predecessors inside of the loop) only
				819	have predecessors from inside of the loop (and are thus dominated by the loop
				820	header). This simplifies transformations such as store-sinking that are built
				821	into LICM.
				822
				823	This pass also guarantees that loops will have exactly one backedge.
				824
				825	Note that the :ref:`simplifycfg <passes-simplifycfg>` pass will clean up blocks
				826	which are split out but end up being unnecessary, so usage of this pass should
				827	not pessimize generated code.
				828
				829	This pass obviously modifies the CFG, but updates loop information and
				830	dominator information.
				831
				832	``-loop-unroll``: Unroll loops
				833	------------------------------
				834
				835	This pass implements a simple loop unroller. It works best when loops have
				836	been canonicalized by the :ref:`indvars <passes-indvars>` pass, allowing it to
				837	determine the trip counts of loops easily.
				838
David Green	9182393	2018-07-19 12:37:00 +0000	[diff] [blame]	839	``-loop-unroll-and-jam``: Unroll and Jam loops
				840	----------------------------------------------
				841
				842	This pass implements a simple unroll and jam classical loop optimisation pass.
				843	It transforms loop from:
				844
				845	.. code-block:: c++
				846
				847	for i.. i+= 1 for i.. i+= 4
				848	for j.. for j..
				849	code(i, j) code(i, j)
				850	code(i+1, j)
				851	code(i+2, j)
				852	code(i+3, j)
				853	remainder loop
				854
				855	Which can be seen as unrolling the outer loop and "jamming" (fusing) the inner
				856	loops into one. When variables or loads can be shared in the new inner loop, this
				857	can lead to significant performance improvements. It uses
				858	:ref:`Dependence Analysis <passes-da>` for proving the transformations are safe.
				859
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	860	``-loop-unswitch``: Unswitch loops
				861	----------------------------------
				862
				863	This pass transforms loops that contain branches on loop-invariant conditions
				864	to have multiple loops. For example, it turns the left into the right code:
				865
				866	.. code-block:: c++
				867
				868	for (...) if (lic)
				869	A for (...)
				870	if (lic) A; B; C
				871	B else
				872	C for (...)
				873	A; C
				874
				875	This can increase the size of the code exponentially (doubling it every time a
				876	loop is unswitched) so we only unswitch if the resultant code will be smaller
				877	than a threshold.
				878
				879	This pass expects :ref:`LICM <passes-licm>` to be run before it to hoist
				880	invariant conditions out of the loop, to make the unswitching opportunity
				881	obvious.
				882
				883	``-loweratomic``: Lower atomic intrinsics to non-atomic form
				884	------------------------------------------------------------
				885
				886	This pass lowers atomic intrinsics to non-atomic form for use in a known
				887	non-preemptible environment.
				888
				889	The pass does not verify that the environment is non-preemptible (in general
				890	this would require knowledge of the entire call graph of the program including
				891	any libraries which may not be available in bitcode form); it simply lowers
				892	every atomic intrinsic.
				893
Mark Seaborn	9bb9615	2014-03-20 19:54:47 +0000	[diff] [blame]	894	``-lowerinvoke``: Lower invokes to calls, for unwindless code generators
				895	------------------------------------------------------------------------
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	896
				897	This transformation is designed for use by code generators which do not yet
Mark Seaborn	9bb9615	2014-03-20 19:54:47 +0000	[diff] [blame]	898	support stack unwinding. This pass converts ``invoke`` instructions to
				899	``call`` instructions, so that any exception-handling ``landingpad`` blocks
				900	become dead code (which can be removed by running the ``-simplifycfg`` pass
				901	afterwards).
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	902
				903	``-lowerswitch``: Lower ``SwitchInst``\ s to branches
				904	-----------------------------------------------------
				905
				906	Rewrites switch instructions with a sequence of branches, which allows targets
				907	to get away with not implementing the switch instruction until it is
				908	convenient.
				909
				910	.. _passes-mem2reg:
				911
				912	``-mem2reg``: Promote Memory to Register
				913	----------------------------------------
				914
				915	This file promotes memory references to be register references. It promotes
				916	alloca instructions which only have loads and stores as uses. An ``alloca`` is
				917	transformed by using dominator frontiers to place phi nodes, then traversing
				918	the function in depth-first order to rewrite loads and stores as appropriate.
				919	This is just the standard SSA construction algorithm to construct "pruned" SSA
				920	form.
				921
				922	``-memcpyopt``: MemCpy Optimization
				923	-----------------------------------
				924
				925	This pass performs various transformations related to eliminating ``memcpy``
				926	calls, or transforming sets of stores into ``memset``\ s.
				927
				928	``-mergefunc``: Merge Functions
				929	-------------------------------
				930
				931	This pass looks for equivalent functions that are mergable and folds them.
				932
Stepan Dyatkovskiy	4912640	2014-12-10 17:42:01 +0000	[diff] [blame]	933	Total-ordering is introduced among the functions set: we define comparison
				934	that answers for every two functions which of them is greater. It allows to
				935	arrange functions into the binary tree.
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	936
Stepan Dyatkovskiy	4912640	2014-12-10 17:42:01 +0000	[diff] [blame]	937	For every new function we check for equivalent in tree.
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	938
Stepan Dyatkovskiy	4912640	2014-12-10 17:42:01 +0000	[diff] [blame]	939	If equivalent exists we fold such functions. If both functions are overridable,
				940	we move the functionality into a new internal function and leave two
				941	overridable thunks to it.
				942
				943	If there is no equivalent, then we add this function to tree.
				944
				945	Lookup routine has O(log(n)) complexity, while whole merging process has
				946	complexity of O(n*log(n)).
				947
				948	Read
				949	:doc:`this <MergeFunctions>`
				950	article for more details.
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	951
				952	``-mergereturn``: Unify function exit nodes
				953	-------------------------------------------
				954
				955	Ensure that functions have at most one ``ret`` instruction in them.
				956	Additionally, it keeps track of which node is the new exit node of the CFG.
				957
				958	``-partial-inliner``: Partial Inliner
				959	-------------------------------------
				960
				961	This pass performs partial inlining, typically by inlining an ``if`` statement
				962	that surrounds the body of the function.
				963
				964	``-prune-eh``: Remove unused exception handling info
				965	----------------------------------------------------
				966
				967	This file implements a simple interprocedural pass which walks the call-graph,
				968	turning invoke instructions into call instructions if and only if the callee
				969	cannot throw an exception. It implements this as a bottom-up traversal of the
				970	call-graph.
				971
				972	``-reassociate``: Reassociate expressions
				973	-----------------------------------------
				974
				975	This pass reassociates commutative expressions in an order that is designed to
				976	promote better constant propagation, GCSE, :ref:`LICM <passes-licm>`, PRE, etc.
				977
				978	For example: 4 + (x + 5) ⇒ x + (4 + 5)
				979
				980	In the implementation of this algorithm, constants are assigned rank = 0,
				981	function arguments are rank = 1, and other values are assigned ranks
				982	corresponding to the reverse post order traversal of current function (starting
				983	at 2), which effectively gives values in deep loops higher rank than values not
				984	in loops.
				985
				986	``-reg2mem``: Demote all values to stack slots
				987	----------------------------------------------
				988
				989	This file demotes all registers to memory references. It is intended to be the
				990	inverse of :ref:`mem2reg <passes-mem2reg>`. By converting to ``load``
				991	instructions, the only values live across basic blocks are ``alloca``
				992	instructions and ``load`` instructions before ``phi`` nodes. It is intended
				993	that this should make CFG hacking much easier. To make later hacking easier,
				994	the entry block is split into two, such that all introduced ``alloca``
				995	instructions (and nothing else) are in the entry block.
				996
David Majnemer	0c4f69f	2016-06-15 00:19:09 +0000	[diff] [blame]	997	``-sroa``: Scalar Replacement of Aggregates
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	998	------------------------------------------------------
				999
				1000	The well-known scalar replacement of aggregates transformation. This transform
				1001	breaks up ``alloca`` instructions of aggregate type (structure or array) into
				1002	individual ``alloca`` instructions for each member if possible. Then, if
				1003	possible, it transforms the individual ``alloca`` instructions into nice clean
				1004	scalar SSA form.
				1005
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	1006	.. _passes-sccp:
				1007
				1008	``-sccp``: Sparse Conditional Constant Propagation
				1009	--------------------------------------------------
				1010
				1011	Sparse conditional constant propagation and merging, which can be summarized
				1012	as:
				1013
				1014	* Assumes values are constant unless proven otherwise
				1015	* Assumes BasicBlocks are dead unless proven otherwise
				1016	* Proves values to be constant, and replaces them with constants
				1017	* Proves conditional branches to be unconditional
				1018
				1019	Note that this pass has a habit of making definitions be dead. It is a good
Dmitri Gribenko	edc399a	2013-05-18 18:01:44 +0000	[diff] [blame]	1020	idea to run a :ref:`DCE <passes-dce>` pass sometime after running this pass.
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	1021
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	1022	.. _passes-simplifycfg:
				1023
				1024	``-simplifycfg``: Simplify the CFG
				1025	----------------------------------
				1026
				1027	Performs dead code elimination and basic block merging. Specifically:
				1028
				1029	* Removes basic blocks with no predecessors.
				1030	* Merges a basic block into its predecessor if there is only one and the
				1031	predecessor only has one successor.
				1032	* Eliminates PHI nodes for basic blocks with a single predecessor.
				1033	* Eliminates a basic block that only contains an unconditional branch.
				1034
				1035	``-sink``: Code sinking
				1036	-----------------------
				1037
				1038	This pass moves instructions into successor blocks, when possible, so that they
				1039	aren't executed on paths where their results aren't needed.
				1040
				1041	``-strip``: Strip all symbols from a module
				1042	-------------------------------------------
				1043
				1044	Performs code stripping. This transformation can delete:
				1045
				1046	* names for virtual registers
				1047	* symbols for internal globals and functions
				1048	* debug information
				1049
				1050	Note that this transformation makes code much less readable, so it should only
				1051	be used in situations where the strip utility would be used, such as reducing
				1052	code size or making it harder to reverse engineer code.
				1053
				1054	``-strip-dead-debug-info``: Strip debug info for unused symbols
				1055	---------------------------------------------------------------
				1056
				1057	.. FIXME: this description is the same as for -strip
				1058
				1059	performs code stripping. this transformation can delete:
				1060
				1061	* names for virtual registers
				1062	* symbols for internal globals and functions
				1063	* debug information
				1064
				1065	note that this transformation makes code much less readable, so it should only
				1066	be used in situations where the strip utility would be used, such as reducing
				1067	code size or making it harder to reverse engineer code.
				1068
				1069	``-strip-dead-prototypes``: Strip Unused Function Prototypes
				1070	------------------------------------------------------------
				1071
				1072	This pass loops over all of the functions in the input module, looking for dead
				1073	declarations and removes them. Dead declarations are declarations of functions
				1074	for which no implementation is available (i.e., declarations for unused library
				1075	functions).
				1076
				1077	``-strip-debug-declare``: Strip all ``llvm.dbg.declare`` intrinsics
				1078	-------------------------------------------------------------------
				1079
				1080	.. FIXME: this description is the same as for -strip
				1081
				1082	This pass implements code stripping. Specifically, it can delete:
				1083
				1084	#. names for virtual registers
				1085	#. symbols for internal globals and functions
				1086	#. debug information
				1087
				1088	Note that this transformation makes code much less readable, so it should only
				1089	be used in situations where the 'strip' utility would be used, such as reducing
				1090	code size or making it harder to reverse engineer code.
				1091
				1092	``-strip-nondebug``: Strip all symbols, except dbg symbols, from a module
				1093	-------------------------------------------------------------------------
				1094
				1095	.. FIXME: this description is the same as for -strip
				1096
				1097	This pass implements code stripping. Specifically, it can delete:
				1098
				1099	#. names for virtual registers
				1100	#. symbols for internal globals and functions
				1101	#. debug information
				1102
				1103	Note that this transformation makes code much less readable, so it should only
				1104	be used in situations where the 'strip' utility would be used, such as reducing
				1105	code size or making it harder to reverse engineer code.
				1106
				1107	``-tailcallelim``: Tail Call Elimination
				1108	----------------------------------------
				1109
				1110	This file transforms calls of the current function (self recursion) followed by
				1111	a return instruction with a branch to the entry of the function, creating a
				1112	loop. This pass also implements the following extensions to the basic
				1113	algorithm:
				1114
				1115	#. Trivial instructions between the call and return do not prevent the
				1116	transformation from taking place, though currently the analysis cannot
				1117	support moving any really useful instructions (only dead ones).
				1118	#. This pass transforms functions that are prevented from being tail recursive
				1119	by an associative expression to use an accumulator variable, thus compiling
				1120	the typical naive factorial or fib implementation into efficient code.
				1121	#. TRE is performed if the function returns void, if the return returns the
				1122	result returned by the call, or if the function returns a run-time constant
				1123	on all exits from the function. It is possible, though unlikely, that the
				1124	return returns something else (like constant 0), and can still be TRE'd. It
				1125	can be TRE'd if all other return instructions in the function return the
				1126	exact same value.
				1127	#. If it can prove that callees do not access theier caller stack frame, they
				1128	are marked as eligible for tail call elimination (by the code generator).
				1129
				1130	Utility Passes
				1131	==============
				1132
				1133	This section describes the LLVM Utility Passes.
				1134
				1135	``-deadarghaX0r``: Dead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE)
				1136	------------------------------------------------------------------------
				1137
				1138	Same as dead argument elimination, but deletes arguments to functions which are
				1139	external. This is only for use by :doc:`bugpoint <Bugpoint>`.
				1140
				1141	``-extract-blocks``: Extract Basic Blocks From Module (for bugpoint use)
				1142	------------------------------------------------------------------------
				1143
				1144	This pass is used by bugpoint to extract all blocks from the module into their
				1145	own functions.
				1146
				1147	``-instnamer``: Assign names to anonymous instructions
				1148	------------------------------------------------------
				1149
				1150	This is a little utility pass that gives instructions names, this is mostly
				1151	useful when diffing the effect of an optimization because deleting an unnamed
				1152	instruction can change all other instruction numbering, making the diff very
				1153	noisy.
				1154
Dmitri Gribenko	e4b3e94	2012-12-11 15:29:37 +0000	[diff] [blame]	1155	.. _passes-verify:
				1156
				1157	``-verify``: Module Verifier
				1158	----------------------------
				1159
				1160	Verifies an LLVM IR code. This is useful to run after an optimization which is
				1161	undergoing testing. Note that llvm-as verifies its input before emitting
				1162	bitcode, and also that malformed bitcode is likely to make LLVM crash. All
				1163	language front-ends are therefore encouraged to verify their output before
				1164	performing optimizing transformations.
				1165
				1166	#. Both of a binary operator's parameters are of the same type.
				1167	#. Verify that the indices of mem access instructions match other operands.
				1168	#. Verify that arithmetic and other things are only performed on first-class
				1169	types. Verify that shifts and logicals only happen on integrals f.e.
				1170	#. All of the constants in a switch statement are of the correct type.
				1171	#. The code is in valid SSA form.
				1172	#. It is illegal to put a label into any other type (like a structure) or to
				1173	return one.
				1174	#. Only phi nodes can be self referential: ``%x = add i32 %x``, ``%x`` is
				1175	invalid.
				1176	#. PHI nodes must have an entry for each predecessor, with no extras.
				1177	#. PHI nodes must be the first thing in a basic block, all grouped together.
				1178	#. PHI nodes must have at least one entry.
				1179	#. All basic blocks should only end with terminator insts, not contain them.
				1180	#. The entry node to a function must not have predecessors.
				1181	#. All Instructions must be embedded into a basic block.
				1182	#. Functions cannot take a void-typed parameter.
				1183	#. Verify that a function's argument list agrees with its declared type.
				1184	#. It is illegal to specify a name for a void value.
				1185	#. It is illegal to have an internal global value with no initializer.
				1186	#. It is illegal to have a ``ret`` instruction that returns a value that does
				1187	not agree with the function return value type.
				1188	#. Function call argument types match the function prototype.
				1189	#. All other things that are tested by asserts spread about the code.
				1190
				1191	Note that this does not provide full security verification (like Java), but
				1192	instead just tries to ensure that code is well-formed.
				1193
				1194	``-view-cfg``: View CFG of function
				1195	-----------------------------------
				1196
				1197	Displays the control flow graph using the GraphViz tool.
				1198
				1199	``-view-cfg-only``: View CFG of function (with no function bodies)
				1200	------------------------------------------------------------------
				1201
				1202	Displays the control flow graph using the GraphViz tool, but omitting function
				1203	bodies.
				1204
				1205	``-view-dom``: View dominance tree of function
				1206	----------------------------------------------
				1207
				1208	Displays the dominator tree using the GraphViz tool.
				1209
				1210	``-view-dom-only``: View dominance tree of function (with no function bodies)
				1211	-----------------------------------------------------------------------------
				1212
				1213	Displays the dominator tree using the GraphViz tool, but omitting function
				1214	bodies.
				1215
				1216	``-view-postdom``: View postdominance tree of function
				1217	------------------------------------------------------
				1218
				1219	Displays the post dominator tree using the GraphViz tool.
				1220
				1221	``-view-postdom-only``: View postdominance tree of function (with no function bodies)
				1222	-------------------------------------------------------------------------------------
				1223
				1224	Displays the post dominator tree using the GraphViz tool, but omitting function
				1225	bodies.
				1226
Michael Kruse	9a395de	2018-12-12 17:32:52 +0000	[diff] [blame]	1227	``-transform-warning``: Report missed forced transformations
				1228	------------------------------------------------------------
				1229
				1230	Emits warnings about not yet applied forced transformations (e.g. from
				1231	``#pragma omp simd``).