blob: 8a84dfd8d0ca09179448db9f57ba7167c6819f49 [file] [log] [blame]
Lei Zhangf18e1f22016-09-12 14:11:46 -04001// 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
15#ifndef SPIRV_TOOLS_OPTIMIZER_HPP_
16#define SPIRV_TOOLS_OPTIMIZER_HPP_
17
18#include <memory>
19#include <string>
20#include <unordered_map>
21#include <vector>
22
23#include "libspirv.hpp"
24#include "message.h"
25
26namespace spvtools {
27
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.
31//
32// Instances of this class provides basic thread-safety guarantee.
33class Optimizer {
34 public:
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.
39 struct PassToken {
40 struct Impl; // Opaque struct for holding inernal data.
41
42 PassToken(std::unique_ptr<Impl>);
43
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&&);
49
50 ~PassToken();
51
52 std::unique_ptr<Impl> impl_; // Unique pointer to internal data.
53 };
54
55 // Constructs an instance with the given target |env|, which is used to decode
56 // the binaries to be optimized later.
57 //
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);
62
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;
68
69 // Destructs this instance.
70 ~Optimizer();
71
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);
75
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
78 // method.
79 Optimizer& RegisterPass(PassToken&& pass);
80
81 // Optimizes the given SPIR-V module |original_binary| and writes the
82 // optimized binary into |optimized_binary|.
83 // Returns true on successful optimization, whether or not the module is
84 // modified. Returns false if errors occur when processing |original_binary|
85 // using any of the registered passes. In that case, no further passes are
86 // excuted and the contents in |optimized_binary| may be invalid.
87 //
88 // It's allowed to alias |original_binary| to the start of |optimized_binary|.
89 bool Run(const uint32_t* original_binary, size_t original_binary_size,
90 std::vector<uint32_t>* optimized_binary) const;
91
92 private:
93 struct Impl; // Opaque struct for holding internal data.
94 std::unique_ptr<Impl> impl_; // Unique pointer to internal data.
95};
96
97// Creates a null pass.
98// A null pass does nothing to the SPIR-V module to be optimized.
99Optimizer::PassToken CreateNullPass();
100
101// Creates a strip-debug-info pass.
102// A strip-debug-info pass removes all debug instructions (as documented in
103// Section 3.32.2 of the SPIR-V spec) of the SPIR-V module to be optimized.
104Optimizer::PassToken CreateStripDebugInfoPass();
105
106// Creates a set-spec-constant-default-value pass.
107// A set-spec-constant-default-value pass sets the default values for the
108// spec constants that have SpecId decorations (i.e., those defined by
109// OpSpecConstant{|True|False} instructions).
110Optimizer::PassToken CreateSetSpecConstantDefaultValuePass(
111 const std::unordered_map<uint32_t, std::string>& id_value_map);
112
113// Creates a freeze-spec-constant-value pass.
114// A freeze-spec-constant pass specializes the value of spec constants to
115// their default values. This pass only processes the spec constants that have
116// SpecId decorations (defined by OpSpecConstant, OpSpecConstantTrue, or
117// OpSpecConstantFalse instructions) and replaces them with their normal
118// counterparts (OpConstant, OpConstantTrue, or OpConstantFalse). The
119// corresponding SpecId annotation instructions will also be removed. This
120// pass does not fold the newly added normal constants and does not process
121// other spec constants defined by OpSpecConstantComposite or
122// OpSpecConstantOp.
123Optimizer::PassToken CreateFreezeSpecConstantValuePass();
124
125// Creates a fold-spec-constant-op-and-composite pass.
126// A fold-spec-constant-op-and-composite pass folds spec constants defined by
127// OpSpecConstantOp or OpSpecConstantComposite instruction, to normal Constants
128// defined by OpConstantTrue, OpConstantFalse, OpConstant, OpConstantNull, or
129// OpConstantComposite instructions. Note that spec constants defined with
130// OpSpecConstant, OpSpecConstantTrue, or OpSpecConstantFalse instructions are
131// not handled, as these instructions indicate their value are not determined
132// and can be changed in future. A spec constant is foldable if all of its
133// value(s) can be determined from the module. E.g., an integer spec constant
134// defined with OpSpecConstantOp instruction can be folded if its value won't
135// change later. This pass will replace the original OpSpecContantOp instruction
136// with an OpConstant instruction. When folding composite spec constants,
137// new instructions may be inserted to define the components of the composite
138// constant first, then the original spec constants will be replaced by
139// OpConstantComposite instructions.
140//
141// There are some operations not supported yet:
142// OpSConvert, OpFConvert, OpQuantizeToF16 and
143// all the operations under Kernel capability.
144// TODO(qining): Add support for the operations listed above.
145Optimizer::PassToken CreateFoldSpecConstantOpAndCompositePass();
146
147// Creates a unify-constant pass.
148// A unify-constant pass de-duplicates the constants. Constants with the exact
149// same value and identical form will be unified and only one constant will
150// be kept for each unique pair of type and value.
151// There are several cases not handled by this pass:
152// 1) Constants defined by OpConstantNull instructions (null constants) and
153// constants defined by OpConstantFalse, OpConstant or OpConstantComposite
154// with value 0 (zero-valued normal constants) are not considered equivalent.
155// So null constants won't be used to replace zero-valued normal constants,
156// vice versa.
157// 2) Whenever there are decorations to the constant's result id id, the
158// constant won't be handled, which means, it won't be used to replace any
159// other constants, neither can other constants replace it.
160// 3) NaN in float point format with different bit patterns are not unified.
161Optimizer::PassToken CreateUnifyConstantPass();
162
163// Creates a eliminate-dead-constant pass.
164// A eliminate-dead-constant pass removes dead constants, including normal
165// contants defined by OpConstant, OpConstantComposite, OpConstantTrue, or
166// OpConstantFalse and spec constants defined by OpSpecConstant,
167// OpSpecConstantComposite, OpSpecConstantTrue, OpSpecConstantFalse or
168// OpSpecConstantOp.
169Optimizer::PassToken CreateEliminateDeadConstantPass();
170
171} // namespace spvtools
172
173#endif // SPIRV_TOOLS_OPTIMIZER_HPP_