1 // Copyright (c) 2016 Google Inc.
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
7 // http://www.apache.org/licenses/LICENSE-2.0
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
15 #ifndef SPIRV_TOOLS_OPTIMIZER_HPP_
16 #define SPIRV_TOOLS_OPTIMIZER_HPP_
21 #include <unordered_map>
24 #include "libspirv.hpp"
28 // C++ interface for SPIR-V optimization functionalities. It wraps the context
29 // (including target environment and the corresponding SPIR-V grammar) and
30 // provides methods for registering optimization passes and optimizing.
32 // Instances of this class provides basic thread-safety guarantee.
35 // The token for an optimization pass. It is returned via one of the
36 // Create*Pass() standalone functions at the end of this header file and
37 // consumed by the RegisterPass() method. Tokens are one-time objects that
38 // only support move; copying is not allowed.
40 struct Impl; // Opaque struct for holding inernal data.
42 PassToken(std::unique_ptr<Impl>);
44 // Tokens can only be moved. Copying is disabled.
45 PassToken(const PassToken&) = delete;
46 PassToken(PassToken&&);
47 PassToken& operator=(const PassToken&) = delete;
48 PassToken& operator=(PassToken&&);
52 std::unique_ptr<Impl> impl_; // Unique pointer to internal data.
55 // Constructs an instance with the given target |env|, which is used to decode
56 // the binaries to be optimized later.
58 // The constructed instance will have an empty message consumer, which just
59 // ignores all messages from the library. Use SetMessageConsumer() to supply
60 // one if messages are of concern.
61 explicit Optimizer(spv_target_env env);
63 // Disables copy/move constructor/assignment operations.
64 Optimizer(const Optimizer&) = delete;
65 Optimizer(Optimizer&&) = delete;
66 Optimizer& operator=(const Optimizer&) = delete;
67 Optimizer& operator=(Optimizer&&) = delete;
69 // Destructs this instance.
72 // Sets the message consumer to the given |consumer|. The |consumer| will be
73 // invoked once for each message communicated from the library.
74 void SetMessageConsumer(MessageConsumer consumer);
76 // Registers the given |pass| to this optimizer. Passes will be run in the
77 // exact order of registration. The token passed in will be consumed by this
79 Optimizer& RegisterPass(PassToken&& pass);
81 // Registers passes that attempt to improve performance of generated code.
82 // This sequence of passes is subject to constant review and will change
84 Optimizer& RegisterPerformancePasses();
86 // Registers passes that attempt to improve the size of generated code.
87 // This sequence of passes is subject to constant review and will change
89 Optimizer& RegisterSizePasses();
91 // Registers passes that attempt to legalize the generated code.
93 // Note: this recipe is specially for legalizing SPIR-V. It should be used
94 // by compilers after translating HLSL source code literally. It should
95 // *not* be used by general workloads for performance or size improvement.
97 // This sequence of passes is subject to constant review and will change
99 Optimizer& RegisterLegalizationPasses();
101 // Optimizes the given SPIR-V module |original_binary| and writes the
102 // optimized binary into |optimized_binary|.
103 // Returns true on successful optimization, whether or not the module is
104 // modified. Returns false if errors occur when processing |original_binary|
105 // using any of the registered passes. In that case, no further passes are
106 // executed and the contents in |optimized_binary| may be invalid.
108 // It's allowed to alias |original_binary| to the start of |optimized_binary|.
109 bool Run(const uint32_t* original_binary, size_t original_binary_size,
110 std::vector<uint32_t>* optimized_binary) const;
112 // Returns a vector of strings with all the pass names added to this
113 // optimizer's pass manager. These strings are valid until the associated
114 // pass manager is destroyed.
115 std::vector<const char*> GetPassNames() const;
117 // Sets the option to print the disassembly before each pass and after the
118 // last pass. If |out| is null, then no output is generated. Otherwise,
119 // output is sent to the |out| output stream.
120 Optimizer& SetPrintAll(std::ostream* out);
123 struct Impl; // Opaque struct for holding internal data.
124 std::unique_ptr<Impl> impl_; // Unique pointer to internal data.
127 // Creates a null pass.
128 // A null pass does nothing to the SPIR-V module to be optimized.
129 Optimizer::PassToken CreateNullPass();
131 // Creates a strip-debug-info pass.
132 // A strip-debug-info pass removes all debug instructions (as documented in
133 // Section 3.32.2 of the SPIR-V spec) of the SPIR-V module to be optimized.
134 Optimizer::PassToken CreateStripDebugInfoPass();
136 // Creates an eliminate-dead-functions pass.
137 // An eliminate-dead-functions pass will remove all functions that are not in
138 // the call trees rooted at entry points and exported functions. These
139 // functions are not needed because they will never be called.
140 Optimizer::PassToken CreateEliminateDeadFunctionsPass();
142 // Creates a set-spec-constant-default-value pass from a mapping from spec-ids
143 // to the default values in the form of string.
144 // A set-spec-constant-default-value pass sets the default values for the
145 // spec constants that have SpecId decorations (i.e., those defined by
146 // OpSpecConstant{|True|False} instructions).
147 Optimizer::PassToken CreateSetSpecConstantDefaultValuePass(
148 const std::unordered_map<uint32_t, std::string>& id_value_map);
150 // Creates a set-spec-constant-default-value pass from a mapping from spec-ids
151 // to the default values in the form of bit pattern.
152 // A set-spec-constant-default-value pass sets the default values for the
153 // spec constants that have SpecId decorations (i.e., those defined by
154 // OpSpecConstant{|True|False} instructions).
155 Optimizer::PassToken CreateSetSpecConstantDefaultValuePass(
156 const std::unordered_map<uint32_t, std::vector<uint32_t>>& id_value_map);
158 // Creates a flatten-decoration pass.
159 // A flatten-decoration pass replaces grouped decorations with equivalent
160 // ungrouped decorations. That is, it replaces each OpDecorationGroup
161 // instruction and associated OpGroupDecorate and OpGroupMemberDecorate
162 // instructions with equivalent OpDecorate and OpMemberDecorate instructions.
163 // The pass does not attempt to preserve debug information for instructions
165 Optimizer::PassToken CreateFlattenDecorationPass();
167 // Creates a freeze-spec-constant-value pass.
168 // A freeze-spec-constant pass specializes the value of spec constants to
169 // their default values. This pass only processes the spec constants that have
170 // SpecId decorations (defined by OpSpecConstant, OpSpecConstantTrue, or
171 // OpSpecConstantFalse instructions) and replaces them with their normal
172 // counterparts (OpConstant, OpConstantTrue, or OpConstantFalse). The
173 // corresponding SpecId annotation instructions will also be removed. This
174 // pass does not fold the newly added normal constants and does not process
175 // other spec constants defined by OpSpecConstantComposite or
177 Optimizer::PassToken CreateFreezeSpecConstantValuePass();
179 // Creates a fold-spec-constant-op-and-composite pass.
180 // A fold-spec-constant-op-and-composite pass folds spec constants defined by
181 // OpSpecConstantOp or OpSpecConstantComposite instruction, to normal Constants
182 // defined by OpConstantTrue, OpConstantFalse, OpConstant, OpConstantNull, or
183 // OpConstantComposite instructions. Note that spec constants defined with
184 // OpSpecConstant, OpSpecConstantTrue, or OpSpecConstantFalse instructions are
185 // not handled, as these instructions indicate their value are not determined
186 // and can be changed in future. A spec constant is foldable if all of its
187 // value(s) can be determined from the module. E.g., an integer spec constant
188 // defined with OpSpecConstantOp instruction can be folded if its value won't
189 // change later. This pass will replace the original OpSpecContantOp instruction
190 // with an OpConstant instruction. When folding composite spec constants,
191 // new instructions may be inserted to define the components of the composite
192 // constant first, then the original spec constants will be replaced by
193 // OpConstantComposite instructions.
195 // There are some operations not supported yet:
196 // OpSConvert, OpFConvert, OpQuantizeToF16 and
197 // all the operations under Kernel capability.
198 // TODO(qining): Add support for the operations listed above.
199 Optimizer::PassToken CreateFoldSpecConstantOpAndCompositePass();
201 // Creates a unify-constant pass.
202 // A unify-constant pass de-duplicates the constants. Constants with the exact
203 // same value and identical form will be unified and only one constant will
204 // be kept for each unique pair of type and value.
205 // There are several cases not handled by this pass:
206 // 1) Constants defined by OpConstantNull instructions (null constants) and
207 // constants defined by OpConstantFalse, OpConstant or OpConstantComposite
208 // with value 0 (zero-valued normal constants) are not considered equivalent.
209 // So null constants won't be used to replace zero-valued normal constants,
211 // 2) Whenever there are decorations to the constant's result id id, the
212 // constant won't be handled, which means, it won't be used to replace any
213 // other constants, neither can other constants replace it.
214 // 3) NaN in float point format with different bit patterns are not unified.
215 Optimizer::PassToken CreateUnifyConstantPass();
217 // Creates a eliminate-dead-constant pass.
218 // A eliminate-dead-constant pass removes dead constants, including normal
219 // contants defined by OpConstant, OpConstantComposite, OpConstantTrue, or
220 // OpConstantFalse and spec constants defined by OpSpecConstant,
221 // OpSpecConstantComposite, OpSpecConstantTrue, OpSpecConstantFalse or
223 Optimizer::PassToken CreateEliminateDeadConstantPass();
225 // Creates a strength-reduction pass.
226 // A strength-reduction pass will look for opportunities to replace an
227 // instruction with an equivalent and less expensive one. For example,
228 // multiplying by a power of 2 can be replaced by a bit shift.
229 Optimizer::PassToken CreateStrengthReductionPass();
231 // Creates a block merge pass.
232 // This pass searches for blocks with a single Branch to a block with no
233 // other predecessors and merges the blocks into a single block. Continue
234 // blocks and Merge blocks are not candidates for the second block.
236 // The pass is most useful after Dead Branch Elimination, which can leave
237 // such sequences of blocks. Merging them makes subsequent passes more
238 // effective, such as single block local store-load elimination.
240 // While this pass reduces the number of occurrences of this sequence, at
241 // this time it does not guarantee all such sequences are eliminated.
243 // Presence of phi instructions can inhibit this optimization. Handling
244 // these is left for future improvements.
245 Optimizer::PassToken CreateBlockMergePass();
247 // Creates an exhaustive inline pass.
248 // An exhaustive inline pass attempts to exhaustively inline all function
249 // calls in all functions in an entry point call tree. The intent is to enable,
250 // albeit through brute force, analysis and optimization across function
251 // calls by subsequent optimization passes. As the inlining is exhaustive,
252 // there is no attempt to optimize for size or runtime performance. Functions
253 // that are not in the call tree of an entry point are not changed.
254 Optimizer::PassToken CreateInlineExhaustivePass();
256 // Creates an opaque inline pass.
257 // An opaque inline pass inlines all function calls in all functions in all
258 // entry point call trees where the called function contains an opaque type
259 // in either its parameter types or return type. An opaque type is currently
260 // defined as Image, Sampler or SampledImage. The intent is to enable, albeit
261 // through brute force, analysis and optimization across these function calls
262 // by subsequent passes in order to remove the storing of opaque types which is
263 // not legal in Vulkan. Functions that are not in the call tree of an entry
264 // point are not changed.
265 Optimizer::PassToken CreateInlineOpaquePass();
267 // Creates a single-block local variable load/store elimination pass.
268 // For every entry point function, do single block memory optimization of
269 // function variables referenced only with non-access-chain loads and stores.
270 // For each targeted variable load, if previous store to that variable in the
271 // block, replace the load's result id with the value id of the store.
272 // If previous load within the block, replace the current load's result id
273 // with the previous load's result id. In either case, delete the current
274 // load. Finally, check if any remaining stores are useless, and delete store
275 // and variable if possible.
277 // The presence of access chain references and function calls can inhibit
278 // the above optimization.
280 // Only modules with relaxed logical addressing (see opt/instruction.h) are
281 // currently processed.
283 // This pass is most effective if preceeded by Inlining and
284 // LocalAccessChainConvert. This pass will reduce the work needed to be done
285 // by LocalSingleStoreElim and LocalMultiStoreElim.
287 // Only functions in the call tree of an entry point are processed.
288 Optimizer::PassToken CreateLocalSingleBlockLoadStoreElimPass();
290 // Create dead branch elimination pass.
291 // For each entry point function, this pass will look for SelectionMerge
292 // BranchConditionals with constant condition and convert to a Branch to
293 // the indicated label. It will delete resulting dead blocks.
295 // For all phi functions in merge block, replace all uses with the id
296 // corresponding to the living predecessor.
298 // Note that some branches and blocks may be left to avoid creating invalid
299 // control flow. Improving this is left to future work.
301 // This pass is most effective when preceeded by passes which eliminate
302 // local loads and stores, effectively propagating constant values where
304 Optimizer::PassToken CreateDeadBranchElimPass();
306 // Creates an SSA local variable load/store elimination pass.
307 // For every entry point function, eliminate all loads and stores of function
308 // scope variables only referenced with non-access-chain loads and stores.
309 // Eliminate the variables as well.
311 // The presence of access chain references and function calls can inhibit
312 // the above optimization.
314 // Only shader modules with relaxed logical addressing (see opt/instruction.h)
315 // are currently processed. Currently modules with any extensions enabled are
316 // not processed. This is left for future work.
318 // This pass is most effective if preceeded by Inlining and
319 // LocalAccessChainConvert. LocalSingleStoreElim and LocalSingleBlockElim
320 // will reduce the work that this pass has to do.
321 Optimizer::PassToken CreateLocalMultiStoreElimPass();
323 // Creates a local access chain conversion pass.
324 // A local access chain conversion pass identifies all function scope
325 // variables which are accessed only with loads, stores and access chains
326 // with constant indices. It then converts all loads and stores of such
327 // variables into equivalent sequences of loads, stores, extracts and inserts.
329 // This pass only processes entry point functions. It currently only converts
330 // non-nested, non-ptr access chains. It does not process modules with
331 // non-32-bit integer types present. Optional memory access options on loads
332 // and stores are ignored as we are only processing function scope variables.
334 // This pass unifies access to these variables to a single mode and simplifies
335 // subsequent analysis and elimination of these variables along with their
336 // loads and stores allowing values to propagate to their points of use where
338 Optimizer::PassToken CreateLocalAccessChainConvertPass();
340 // Creates a local single store elimination pass.
341 // For each entry point function, this pass eliminates loads and stores for
342 // function scope variable that are stored to only once, where possible. Only
343 // whole variable loads and stores are eliminated; access-chain references are
344 // not optimized. Replace all loads of such variables with the value that is
345 // stored and eliminate any resulting dead code.
347 // Currently, the presence of access chains and function calls can inhibit this
348 // pass, however the Inlining and LocalAccessChainConvert passes can make it
349 // more effective. In additional, many non-load/store memory operations are
350 // not supported and will prohibit optimization of a function. Support of
351 // these operations are future work.
353 // Only shader modules with relaxed logical addressing (see opt/instruction.h)
354 // are currently processed.
356 // This pass will reduce the work needed to be done by LocalSingleBlockElim
357 // and LocalMultiStoreElim and can improve the effectiveness of other passes
358 // such as DeadBranchElimination which depend on values for their analysis.
359 Optimizer::PassToken CreateLocalSingleStoreElimPass();
361 // Creates an insert/extract elimination pass.
362 // This pass processes each entry point function in the module, searching for
363 // extracts on a sequence of inserts. It further searches the sequence for an
364 // insert with indices identical to the extract. If such an insert can be
365 // found before hitting a conflicting insert, the extract's result id is
366 // replaced with the id of the values from the insert.
368 // Besides removing extracts this pass enables subsequent dead code elimination
369 // passes to delete the inserts. This pass performs best after access chains are
370 // converted to inserts and extracts and local loads and stores are eliminated.
371 Optimizer::PassToken CreateInsertExtractElimPass();
373 // Creates a dead insert elimination pass.
374 // This pass processes each entry point function in the module, searching for
375 // unreferenced inserts into composite types. These are most often unused
376 // stores to vector components. They are unused because they are never
377 // referenced, or because there is another insert to the same component between
378 // the insert and the reference. After removing the inserts, dead code
379 // elimination is attempted on the inserted values.
381 // This pass performs best after access chains are converted to inserts and
382 // extracts and local loads and stores are eliminated. While executing this
383 // pass can be advantageous on its own, it is also advantageous to execute
384 // this pass after CreateInsertExtractPass() as it will remove any unused
385 // inserts created by that pass.
386 Optimizer::PassToken CreateDeadInsertElimPass();
388 // Creates a pass to consolidate uniform references.
389 // For each entry point function in the module, first change all constant index
390 // access chain loads into equivalent composite extracts. Then consolidate
391 // identical uniform loads into one uniform load. Finally, consolidate
392 // identical uniform extracts into one uniform extract. This may require
393 // moving a load or extract to a point which dominates all uses.
395 // This pass requires a module to have structured control flow ie shader
396 // capability. It also requires logical addressing ie Addresses capability
397 // is not enabled. It also currently does not support any extensions.
399 // This pass currently only optimizes loads with a single index.
400 Optimizer::PassToken CreateCommonUniformElimPass();
402 // Create aggressive dead code elimination pass
403 // This pass eliminates unused code from the module. In addition,
404 // it detects and eliminates code which may have spurious uses but which do
405 // not contribute to the output of the function. The most common cause of
406 // such code sequences is summations in loops whose result is no longer used
407 // due to dead code elimination. This optimization has additional compile
408 // time cost over standard dead code elimination.
410 // This pass only processes entry point functions. It also only processes
411 // shaders with relaxed logical addressing (see opt/instruction.h). It
412 // currently will not process functions with function calls. Unreachable
413 // functions are deleted.
415 // This pass will be made more effective by first running passes that remove
416 // dead control flow and inlines function calls.
418 // This pass can be especially useful after running Local Access Chain
419 // Conversion, which tends to cause cycles of dead code to be left after
420 // Store/Load elimination passes are completed. These cycles cannot be
421 // eliminated with standard dead code elimination.
422 Optimizer::PassToken CreateAggressiveDCEPass();
424 // Creates a compact ids pass.
425 // The pass remaps result ids to a compact and gapless range starting from %1.
426 Optimizer::PassToken CreateCompactIdsPass();
428 // Creates a remove duplicate pass.
429 // This pass removes various duplicates:
430 // * duplicate capabilities;
431 // * duplicate extended instruction imports;
432 // * duplicate types;
433 // * duplicate decorations.
434 Optimizer::PassToken CreateRemoveDuplicatesPass();
436 // Creates a CFG cleanup pass.
437 // This pass removes cruft from the control flow graph of functions that are
438 // reachable from entry points and exported functions. It currently includes the
439 // following functionality:
441 // - Removal of unreachable basic blocks.
442 Optimizer::PassToken CreateCFGCleanupPass();
444 // Create dead variable elimination pass.
445 // This pass will delete module scope variables, along with their decorations,
446 // that are not referenced.
447 Optimizer::PassToken CreateDeadVariableEliminationPass();
449 // Create merge return pass.
450 // This pass replaces all returns with unconditional branches to a new block
451 // containing a return. If necessary, this new block will contain a PHI node to
452 // select the correct return value.
454 // This pass does not consider unreachable code, nor does it perform any other
457 // This pass does not currently support structured control flow. It bails out if
458 // the shader capability is detected.
459 Optimizer::PassToken CreateMergeReturnPass();
461 // Create value numbering pass.
462 // This pass will look for instructions in the same basic block that compute the
463 // same value, and remove the redundant ones.
464 Optimizer::PassToken CreateLocalRedundancyEliminationPass();
466 // Create global value numbering pass.
467 // This pass will look for instructions where the same value is computed on all
468 // paths leading to the instruction. Those instructions are deleted.
469 Optimizer::PassToken CreateRedundancyEliminationPass();
471 // Create scalar replacement pass.
472 // This pass replaces composite function scope variables with variables for each
473 // element if those elements are accessed individually.
474 Optimizer::PassToken CreateScalarReplacementPass();
476 // Create a private to local pass.
477 // This pass looks for variables delcared in the private storage class that are
478 // used in only one function. Those variables are moved to the function storage
479 // class in the function that they are used.
480 Optimizer::PassToken CreatePrivateToLocalPass();
482 // Creates a conditional constant propagation (CCP) pass.
483 // This pass implements the SSA-CCP algorithm in
485 // Constant propagation with conditional branches,
486 // Wegman and Zadeck, ACM TOPLAS 13(2):181-210.
488 // Constant values in expressions and conditional jumps are folded and
489 // simplified. This may reduce code size by removing never executed jump targets
490 // and computations with constant operands.
491 Optimizer::PassToken CreateCCPPass();
493 // Creates a workaround driver bugs pass. This pass attempts to work around
494 // a known driver bug (issue #1209) by identifying the bad code sequences and
497 // Current workaround: Avoid OpUnreachable instructions in loops.
498 Optimizer::PassToken CreateWorkaround1209Pass();
500 // Creates a pass that converts if-then-else like assignments into OpSelect.
501 Optimizer::PassToken CreateIfConversionPass();
503 // Creates a pass that will replace instructions that are not valid for the
504 // current shader stage by constants. Has no effect on non-shader modules.
505 Optimizer::PassToken CreateReplaceInvalidOpcodePass();
507 // Creates a pass that simplifies instructions using the instruction folder.
508 Optimizer::PassToken CreateSimplificationPass();
510 } // namespace spvtools
512 #endif // SPIRV_TOOLS_OPTIMIZER_HPP_