optimizer.hpp 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371
  1. // Copyright (c) 2016 Google Inc.
  2. //
  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
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  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.
  14. #ifndef SPIRV_TOOLS_OPTIMIZER_HPP_
  15. #define SPIRV_TOOLS_OPTIMIZER_HPP_
  16. #include <memory>
  17. #include <string>
  18. #include <unordered_map>
  19. #include <vector>
  20. #include "libspirv.hpp"
  21. namespace spvtools {
  22. // C++ interface for SPIR-V optimization functionalities. It wraps the context
  23. // (including target environment and the corresponding SPIR-V grammar) and
  24. // provides methods for registering optimization passes and optimizing.
  25. //
  26. // Instances of this class provides basic thread-safety guarantee.
  27. class Optimizer {
  28. public:
  29. // The token for an optimization pass. It is returned via one of the
  30. // Create*Pass() standalone functions at the end of this header file and
  31. // consumed by the RegisterPass() method. Tokens are one-time objects that
  32. // only support move; copying is not allowed.
  33. struct PassToken {
  34. struct Impl; // Opaque struct for holding inernal data.
  35. PassToken(std::unique_ptr<Impl>);
  36. // Tokens can only be moved. Copying is disabled.
  37. PassToken(const PassToken&) = delete;
  38. PassToken(PassToken&&);
  39. PassToken& operator=(const PassToken&) = delete;
  40. PassToken& operator=(PassToken&&);
  41. ~PassToken();
  42. std::unique_ptr<Impl> impl_; // Unique pointer to internal data.
  43. };
  44. // Constructs an instance with the given target |env|, which is used to decode
  45. // the binaries to be optimized later.
  46. //
  47. // The constructed instance will have an empty message consumer, which just
  48. // ignores all messages from the library. Use SetMessageConsumer() to supply
  49. // one if messages are of concern.
  50. explicit Optimizer(spv_target_env env);
  51. // Disables copy/move constructor/assignment operations.
  52. Optimizer(const Optimizer&) = delete;
  53. Optimizer(Optimizer&&) = delete;
  54. Optimizer& operator=(const Optimizer&) = delete;
  55. Optimizer& operator=(Optimizer&&) = delete;
  56. // Destructs this instance.
  57. ~Optimizer();
  58. // Sets the message consumer to the given |consumer|. The |consumer| will be
  59. // invoked once for each message communicated from the library.
  60. void SetMessageConsumer(MessageConsumer consumer);
  61. // Registers the given |pass| to this optimizer. Passes will be run in the
  62. // exact order of registration. The token passed in will be consumed by this
  63. // method.
  64. Optimizer& RegisterPass(PassToken&& pass);
  65. // Optimizes the given SPIR-V module |original_binary| and writes the
  66. // optimized binary into |optimized_binary|.
  67. // Returns true on successful optimization, whether or not the module is
  68. // modified. Returns false if errors occur when processing |original_binary|
  69. // using any of the registered passes. In that case, no further passes are
  70. // excuted and the contents in |optimized_binary| may be invalid.
  71. //
  72. // It's allowed to alias |original_binary| to the start of |optimized_binary|.
  73. bool Run(const uint32_t* original_binary, size_t original_binary_size,
  74. std::vector<uint32_t>* optimized_binary) const;
  75. private:
  76. struct Impl; // Opaque struct for holding internal data.
  77. std::unique_ptr<Impl> impl_; // Unique pointer to internal data.
  78. };
  79. // Creates a null pass.
  80. // A null pass does nothing to the SPIR-V module to be optimized.
  81. Optimizer::PassToken CreateNullPass();
  82. // Creates a strip-debug-info pass.
  83. // A strip-debug-info pass removes all debug instructions (as documented in
  84. // Section 3.32.2 of the SPIR-V spec) of the SPIR-V module to be optimized.
  85. Optimizer::PassToken CreateStripDebugInfoPass();
  86. // Creates a set-spec-constant-default-value pass from a mapping from spec-ids
  87. // to the default values in the form of string.
  88. // A set-spec-constant-default-value pass sets the default values for the
  89. // spec constants that have SpecId decorations (i.e., those defined by
  90. // OpSpecConstant{|True|False} instructions).
  91. Optimizer::PassToken CreateSetSpecConstantDefaultValuePass(
  92. const std::unordered_map<uint32_t, std::string>& id_value_map);
  93. // Creates a set-spec-constant-default-value pass from a mapping from spec-ids
  94. // to the default values in the form of bit pattern.
  95. // A set-spec-constant-default-value pass sets the default values for the
  96. // spec constants that have SpecId decorations (i.e., those defined by
  97. // OpSpecConstant{|True|False} instructions).
  98. Optimizer::PassToken CreateSetSpecConstantDefaultValuePass(
  99. const std::unordered_map<uint32_t, std::vector<uint32_t>>& id_value_map);
  100. // Creates a flatten-decoration pass.
  101. // A flatten-decoration pass replaces grouped decorations with equivalent
  102. // ungrouped decorations. That is, it replaces each OpDecorationGroup
  103. // instruction and associated OpGroupDecorate and OpGroupMemberDecorate
  104. // instructions with equivalent OpDecorate and OpMemberDecorate instructions.
  105. // The pass does not attempt to preserve debug information for instructions
  106. // it removes.
  107. Optimizer::PassToken CreateFlattenDecorationPass();
  108. // Creates a freeze-spec-constant-value pass.
  109. // A freeze-spec-constant pass specializes the value of spec constants to
  110. // their default values. This pass only processes the spec constants that have
  111. // SpecId decorations (defined by OpSpecConstant, OpSpecConstantTrue, or
  112. // OpSpecConstantFalse instructions) and replaces them with their normal
  113. // counterparts (OpConstant, OpConstantTrue, or OpConstantFalse). The
  114. // corresponding SpecId annotation instructions will also be removed. This
  115. // pass does not fold the newly added normal constants and does not process
  116. // other spec constants defined by OpSpecConstantComposite or
  117. // OpSpecConstantOp.
  118. Optimizer::PassToken CreateFreezeSpecConstantValuePass();
  119. // Creates a fold-spec-constant-op-and-composite pass.
  120. // A fold-spec-constant-op-and-composite pass folds spec constants defined by
  121. // OpSpecConstantOp or OpSpecConstantComposite instruction, to normal Constants
  122. // defined by OpConstantTrue, OpConstantFalse, OpConstant, OpConstantNull, or
  123. // OpConstantComposite instructions. Note that spec constants defined with
  124. // OpSpecConstant, OpSpecConstantTrue, or OpSpecConstantFalse instructions are
  125. // not handled, as these instructions indicate their value are not determined
  126. // and can be changed in future. A spec constant is foldable if all of its
  127. // value(s) can be determined from the module. E.g., an integer spec constant
  128. // defined with OpSpecConstantOp instruction can be folded if its value won't
  129. // change later. This pass will replace the original OpSpecContantOp instruction
  130. // with an OpConstant instruction. When folding composite spec constants,
  131. // new instructions may be inserted to define the components of the composite
  132. // constant first, then the original spec constants will be replaced by
  133. // OpConstantComposite instructions.
  134. //
  135. // There are some operations not supported yet:
  136. // OpSConvert, OpFConvert, OpQuantizeToF16 and
  137. // all the operations under Kernel capability.
  138. // TODO(qining): Add support for the operations listed above.
  139. Optimizer::PassToken CreateFoldSpecConstantOpAndCompositePass();
  140. // Creates a unify-constant pass.
  141. // A unify-constant pass de-duplicates the constants. Constants with the exact
  142. // same value and identical form will be unified and only one constant will
  143. // be kept for each unique pair of type and value.
  144. // There are several cases not handled by this pass:
  145. // 1) Constants defined by OpConstantNull instructions (null constants) and
  146. // constants defined by OpConstantFalse, OpConstant or OpConstantComposite
  147. // with value 0 (zero-valued normal constants) are not considered equivalent.
  148. // So null constants won't be used to replace zero-valued normal constants,
  149. // vice versa.
  150. // 2) Whenever there are decorations to the constant's result id id, the
  151. // constant won't be handled, which means, it won't be used to replace any
  152. // other constants, neither can other constants replace it.
  153. // 3) NaN in float point format with different bit patterns are not unified.
  154. Optimizer::PassToken CreateUnifyConstantPass();
  155. // Creates a eliminate-dead-constant pass.
  156. // A eliminate-dead-constant pass removes dead constants, including normal
  157. // contants defined by OpConstant, OpConstantComposite, OpConstantTrue, or
  158. // OpConstantFalse and spec constants defined by OpSpecConstant,
  159. // OpSpecConstantComposite, OpSpecConstantTrue, OpSpecConstantFalse or
  160. // OpSpecConstantOp.
  161. Optimizer::PassToken CreateEliminateDeadConstantPass();
  162. // Creates a block merge pass.
  163. // This pass searches for blocks with a single Branch to a block with no
  164. // other predecessors and merges the blocks into a single block. Continue
  165. // blocks and Merge blocks are not candidates for the second block.
  166. //
  167. // The pass is most useful after Dead Branch Elimination, which can leave
  168. // such sequences of blocks. Merging them makes subsequent passes more
  169. // effective, such as single block local store-load elimination.
  170. //
  171. // While this pass reduces the number of occurrences of this sequence, at
  172. // this time it does not guarantee all such sequences are eliminated.
  173. //
  174. // Presence of phi instructions can inhibit this optimization. Handling
  175. // these is left for future improvements.
  176. Optimizer::PassToken CreateBlockMergePass();
  177. // Creates an inline pass.
  178. // An inline pass exhaustively inlines all function calls in all functions
  179. // designated as an entry point. The intent is to enable, albeit through
  180. // brute force, analysis and optimization across function calls by subsequent
  181. // passes. As the inlining is exhaustive, there is no attempt to optimize for
  182. // size or runtime performance. Functions that are not designated as entry
  183. // points are not changed.
  184. Optimizer::PassToken CreateInlinePass();
  185. // Creates a single-block local variable load/store elimination pass.
  186. // For every entry point function, do single block memory optimization of
  187. // function variables referenced only with non-access-chain loads and stores.
  188. // For each targeted variable load, if previous store to that variable in the
  189. // block, replace the load's result id with the value id of the store.
  190. // If previous load within the block, replace the current load's result id
  191. // with the previous load's result id. In either case, delete the current
  192. // load. Finally, check if any remaining stores are useless, and delete store
  193. // and variable if possible.
  194. //
  195. // The presence of access chain references and function calls can inhibit
  196. // the above optimization.
  197. //
  198. // Only modules with logical addressing are currently processed.
  199. //
  200. // This pass is most effective if preceeded by Inlining and
  201. // LocalAccessChainConvert. This pass will reduce the work needed to be done
  202. // by LocalSingleStoreElim and LocalMultiStoreElim.
  203. Optimizer::PassToken CreateLocalSingleBlockLoadStoreElimPass();
  204. // Create dead branch elimination pass.
  205. // For each entry point function, this pass will look for SelectionMerge
  206. // BranchConditionals with constant condition and convert to a Branch to
  207. // the indicated label. It will delete resulting dead blocks.
  208. //
  209. // This pass only works on shaders (guaranteed to have structured control
  210. // flow). Note that some such branches and blocks may be left to avoid
  211. // creating invalid control flow. Improving this is left to future work.
  212. //
  213. // This pass is most effective when preceeded by passes which eliminate
  214. // local loads and stores, effectively propagating constant values where
  215. // possible.
  216. Optimizer::PassToken CreateDeadBranchElimPass();
  217. // Creates an SSA local variable load/store elimination pass.
  218. // For every entry point function, eliminate all loads and stores of function
  219. // scope variables only referenced with non-access-chain loads and stores.
  220. // Eliminate the variables as well.
  221. //
  222. // The presence of access chain references and function calls can inhibit
  223. // the above optimization.
  224. //
  225. // Only shader modules with logical addressing are currently processed.
  226. // Currently modules with any extensions enabled are not processed. This
  227. // is left for future work.
  228. //
  229. // This pass is most effective if preceeded by Inlining and
  230. // LocalAccessChainConvert. LocalSingleStoreElim and LocalSingleBlockElim
  231. // will reduce the work that this pass has to do.
  232. Optimizer::PassToken CreateLocalMultiStoreElimPass();
  233. // Creates a local access chain conversion pass.
  234. // A local access chain conversion pass identifies all function scope
  235. // variables which are accessed only with loads, stores and access chains
  236. // with constant indices. It then converts all loads and stores of such
  237. // variables into equivalent sequences of loads, stores, extracts and inserts.
  238. //
  239. // This pass only processes entry point functions. It currently only converts
  240. // non-nested, non-ptr access chains. It does not process modules with
  241. // non-32-bit integer types present. Optional memory access options on loads
  242. // and stores are ignored as we are only processing function scope variables.
  243. //
  244. // This pass unifies access to these variables to a single mode and simplifies
  245. // subsequent analysis and elimination of these variables along with their
  246. // loads and stores allowing values to propagate to their points of use where
  247. // possible.
  248. Optimizer::PassToken CreateLocalAccessChainConvertPass();
  249. // Create aggressive dead code elimination pass
  250. // This pass eliminates unused code from functions. In addition,
  251. // it detects and eliminates code which may have spurious uses but which do
  252. // not contribute to the output of the function. The most common cause of
  253. // such code sequences is summations in loops whose result is no longer used
  254. // due to dead code elimination. This optimization has additional compile
  255. // time cost over standard dead code elimination.
  256. //
  257. // This pass only processes entry point functions. It also only processes
  258. // shaders with logical addressing. It currently will not process functions
  259. // with function calls. It currently only supports the GLSL.std.450 extended
  260. // instruction set. It currently does not support any extensions.
  261. //
  262. // This pass will be made more effective by first running passes that remove
  263. // dead control flow and inlines function calls.
  264. //
  265. // This pass can be especially useful after running Local Access Chain
  266. // Conversion, which tends to cause cycles of dead code to be left after
  267. // Store/Load elimination passes are completed. These cycles cannot be
  268. // eliminated with standard dead code elimination.
  269. Optimizer::PassToken CreateAggressiveDCEPass();
  270. // Creates a local single store elimination pass.
  271. // For each entry point function, this pass eliminates loads and stores for
  272. // function scope variable that are stored to only once, where possible. Only
  273. // whole variable loads and stores are eliminated; access-chain references are
  274. // not optimized. Replace all loads of such variables with the value that is
  275. // stored and eliminate any resulting dead code.
  276. //
  277. // Currently, the presence of access chains and function calls can inhibit this
  278. // pass, however the Inlining and LocalAccessChainConvert passes can make it
  279. // more effective. In additional, many non-load/store memory operations are
  280. // not supported and will prohibit optimization of a function. Support of
  281. // these operations are future work.
  282. //
  283. // This pass will reduce the work needed to be done by LocalSingleBlockElim
  284. // and LocalMultiStoreElim and can improve the effectiveness of other passes
  285. // such as DeadBranchElimination which depend on values for their analysis.
  286. Optimizer::PassToken CreateLocalSingleStoreElimPass();
  287. // Creates an insert/extract elimination pass.
  288. // This pass processes each entry point function in the module, searching for
  289. // extracts on a sequence of inserts. It further searches the sequence for an
  290. // insert with indices identical to the extract. If such an insert can be
  291. // found before hitting a conflicting insert, the extract's result id is
  292. // replaced with the id of the values from the insert.
  293. //
  294. // Besides removing extracts this pass enables subsequent dead code elimination
  295. // passes to delete the inserts. This pass performs best after access chains are
  296. // converted to inserts and extracts and local loads and stores are eliminated.
  297. Optimizer::PassToken CreateInsertExtractElimPass();
  298. // Create dead branch elimination pass.
  299. // For each entry point function, this pass will look for BranchConditionals
  300. // with constant condition and convert to a branch. The BranchConditional must
  301. // be preceeded by OpSelectionMerge. For all phi functions in merge block,
  302. // replace all uses with the id corresponding to the living predecessor.
  303. //
  304. // This pass is most effective when preceeded by passes which eliminate
  305. // local loads and stores, effectively propagating constant values where
  306. // possible.
  307. Optimizer::PassToken CreateDeadBranchElimPass();
  308. // Create aggressive dead code elimination pass
  309. // This pass eliminates unused code from functions. In addition,
  310. // it detects and eliminates code which may have spurious uses but which do
  311. // not contribute to the output of the function. The most common cause of
  312. // such code sequences is summations in loops whose result is no longer used
  313. // due to dead code elimination. This optimization has additional compile
  314. // time cost over standard dead code elimination.
  315. //
  316. // This pass only processes entry point functions. It also only processes
  317. // shaders with logical addressing. It currently will not process functions
  318. // with function calls.
  319. //
  320. // This pass will be made more effective by first running passes that remove
  321. // dead control flow and inlines function calls.
  322. //
  323. // This pass can be especially useful after running Local Access Chain
  324. // Conversion, which tends to cause cycles of dead code to be left after
  325. // Store/Load elimination passes are completed. These cycles cannot be
  326. // eliminated with standard dead code elimination.
  327. Optimizer::PassToken CreateAggressiveDCEPass();
  328. // Creates a compact ids pass.
  329. // The pass remaps result ids to a compact and gapless range starting from %1.
  330. Optimizer::PassToken CreateCompactIdsPass();
  331. } // namespace spvtools
  332. #endif // SPIRV_TOOLS_OPTIMIZER_HPP_