Debian Codegraph @

third_party/spirv-tools/source/opt/instrument_pass.h

raw
1 // Copyright (c) 2018 The Khronos Group Inc.
2 // Copyright (c) 2018 Valve Corporation
3 // Copyright (c) 2018 LunarG Inc.
4 //
5 // Licensed under the Apache License, Version 2.0 (the "License");
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
8 //
9 // http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16
17 #ifndef LIBSPIRV_OPT_INSTRUMENT_PASS_H_
18 #define LIBSPIRV_OPT_INSTRUMENT_PASS_H_
19
20 #include <list>
21 #include <memory>
22 #include <vector>
23
24 #include "source/opt/ir_builder.h"
25 #include "source/opt/pass.h"
26 #include "spirv-tools/instrument.hpp"
27
28 // This is a base class to assist in the creation of passes which instrument
29 // shader modules. More specifically, passes which replace instructions with a
30 // larger and more capable set of instructions. Commonly, these new
31 // instructions will add testing of operands and execute different
32 // instructions depending on the outcome, including outputting of debug
33 // information into a buffer created especially for that purpose.
34 //
35 // This class contains helper functions to create an InstProcessFunction,
36 // which is the heart of any derived class implementing a specific
37 // instrumentation pass. It takes an instruction as an argument, decides
38 // if it should be instrumented, and generates code to replace it. This class
39 // also supplies function InstProcessEntryPointCallTree which applies the
40 // InstProcessFunction to every reachable instruction in a module and replaces
41 // the instruction with new instructions if generated.
42 //
43 // Chief among the helper functions are output code generation functions,
44 // used to generate code in the shader which writes data to output buffers
45 // associated with that validation. Currently one such function,
46 // GenDebugStreamWrite, exists. Other such functions may be added in the
47 // future. Each is accompanied by documentation describing the format of
48 // its output buffer.
49 //
50 // A validation pass may read or write multiple buffers. All such buffers
51 // are located in a single debug descriptor set whose index is passed at the
52 // creation of the instrumentation pass. The bindings of the buffers used by
53 // a validation pass are permanantly assigned and fixed and documented by
54 // the kDebugOutput* static consts.
55
56 namespace spvtools {
57 namespace opt {
58
59 // Validation Ids
60 // These are used to identify the general validation being done and map to
61 // its output buffers.
62 static const uint32_t kInstValidationIdBindless = 0;
63 static const uint32_t kInstValidationIdBuffAddr = 1;
64 static const uint32_t kInstValidationIdDebugPrintf = 2;
65
66 class InstrumentPass : public Pass {
67 using cbb_ptr = const BasicBlock*;
68
69 public:
70 using InstProcessFunction =
71 std::function<void(BasicBlock::iterator, UptrVectorIterator<BasicBlock>,
72 uint32_t, std::vector<std::unique_ptr<BasicBlock>>*)>;
73
74 ~InstrumentPass() override = default;
75
76 IRContext::Analysis GetPreservedAnalyses() override {
77 return IRContext::kAnalysisDefUse | IRContext::kAnalysisDecorations |
78 IRContext::kAnalysisCombinators | IRContext::kAnalysisNameMap |
79 IRContext::kAnalysisBuiltinVarId | IRContext::kAnalysisConstants;
80 }
81
82 protected:
83 // Create instrumentation pass for |validation_id| which utilizes descriptor
84 // set |desc_set| for debug input and output buffers and writes |shader_id|
85 // into debug output records. |opt_direct_reads| indicates that the pass
86 // will see direct input buffer reads and should prepare to optimize them.
87 InstrumentPass(uint32_t desc_set, uint32_t shader_id, uint32_t validation_id,
88 bool opt_direct_reads = false)
89 : Pass(),
90 desc_set_(desc_set),
91 shader_id_(shader_id),
92 validation_id_(validation_id),
93 opt_direct_reads_(opt_direct_reads) {}
94
95 // Initialize state for instrumentation of module.
96 void InitializeInstrument();
97
98 // Call |pfn| on all instructions in all functions in the call tree of the
99 // entry points in |module|. If code is generated for an instruction, replace
100 // the instruction's block with the new blocks that are generated. Continue
101 // processing at the top of the last new block.
102 bool InstProcessEntryPointCallTree(InstProcessFunction& pfn);
103
104 // Move all code in |ref_block_itr| preceding the instruction |ref_inst_itr|
105 // to be instrumented into block |new_blk_ptr|.
106 void MovePreludeCode(BasicBlock::iterator ref_inst_itr,
107 UptrVectorIterator<BasicBlock> ref_block_itr,
108 std::unique_ptr<BasicBlock>* new_blk_ptr);
109
110 // Move all code in |ref_block_itr| succeeding the instruction |ref_inst_itr|
111 // to be instrumented into block |new_blk_ptr|.
112 void MovePostludeCode(UptrVectorIterator<BasicBlock> ref_block_itr,
113 BasicBlock* new_blk_ptr);
114
115 // Generate instructions in |builder| which will atomically fetch and
116 // increment the size of the debug output buffer stream of the current
117 // validation and write a record to the end of the stream, if enough space
118 // in the buffer remains. The record will contain the index of the function
119 // and instruction within that function |func_idx, instruction_idx| which
120 // generated the record. It will also contain additional information to
121 // identify the instance of the shader, depending on the stage |stage_idx|
122 // of the shader. Finally, the record will contain validation-specific
123 // data contained in |validation_ids| which will identify the validation
124 // error as well as the values involved in the error.
125 //
126 // The output buffer binding written to by the code generated by the function
127 // is determined by the validation id specified when each specific
128 // instrumentation pass is created.
129 //
130 // The output buffer is a sequence of 32-bit values with the following
131 // format (where all elements are unsigned 32-bit unless otherwise noted):
132 //
133 // Size
134 // Record0
135 // Record1
136 // Record2
137 // ...
138 //
139 // Size is the number of 32-bit values that have been written or
140 // attempted to be written to the output buffer, excluding the Size. It is
141 // initialized to 0. If the size of attempts to write the buffer exceeds
142 // the actual size of the buffer, it is possible that this field can exceed
143 // the actual size of the buffer.
144 //
145 // Each Record* is a variable-length sequence of 32-bit values with the
146 // following format defined using static const offsets in the .cpp file:
147 //
148 // Record Size
149 // Shader ID
150 // Instruction Index
151 // Stage
152 // Stage-specific Word 0
153 // Stage-specific Word 1
154 // ...
155 // Validation Error Code
156 // Validation-specific Word 0
157 // Validation-specific Word 1
158 // Validation-specific Word 2
159 // ...
160 //
161 // Each record consists of three subsections: members common across all
162 // validation, members specific to the stage, and members specific to a
163 // validation.
164 //
165 // The Record Size is the number of 32-bit words in the record, including
166 // the Record Size word.
167 //
168 // Shader ID is a value that identifies which shader has generated the
169 // validation error. It is passed when the instrumentation pass is created.
170 //
171 // The Instruction Index is the position of the instruction within the
172 // SPIR-V file which is in error.
173 //
174 // The Stage is the pipeline stage which has generated the error as defined
175 // by the SpvExecutionModel_ enumeration. This is used to interpret the
176 // following Stage-specific words.
177 //
178 // The Stage-specific Words identify which invocation of the shader generated
179 // the error. Every stage will write a fixed number of words. Vertex shaders
180 // will write the Vertex and Instance ID. Fragment shaders will write
181 // FragCoord.xy. Compute shaders will write the GlobalInvocation ID.
182 // The tesselation eval shader will write the Primitive ID and TessCoords.uv.
183 // The tesselation control shader and geometry shader will write the
184 // Primitive ID and Invocation ID.
185 //
186 // The Validation Error Code specifies the exact error which has occurred.
187 // These are enumerated with the kInstError* static consts. This allows
188 // multiple validation layers to use the same, single output buffer.
189 //
190 // The Validation-specific Words are a validation-specific number of 32-bit
191 // words which give further information on the validation error that
192 // occurred. These are documented further in each file containing the
193 // validation-specific class which derives from this base class.
194 //
195 // Because the code that is generated checks against the size of the buffer
196 // before writing, the size of the debug out buffer can be used by the
197 // validation layer to control the number of error records that are written.
198 void GenDebugStreamWrite(uint32_t instruction_idx, uint32_t stage_idx,
199 const std::vector<uint32_t>& validation_ids,
200 InstructionBuilder* builder);
201
202 // Return true if all instructions in |ids| are constants or spec constants.
203 bool AllConstant(const std::vector<uint32_t>& ids);
204
205 // Generate in |builder| instructions to read the unsigned integer from the
206 // input buffer specified by the offsets in |offset_ids|. Given offsets
207 // o0, o1, ... oN, and input buffer ibuf, return the id for the value:
208 //
209 // ibuf[...ibuf[ibuf[o0]+o1]...+oN]
210 //
211 // The binding and the format of the input buffer is determined by each
212 // specific validation, which is specified at the creation of the pass.
213 uint32_t GenDebugDirectRead(const std::vector<uint32_t>& offset_ids,
214 InstructionBuilder* builder);
215
216 // Generate code to convert integer |value_id| to 32bit, if needed. Return
217 // an id to the 32bit equivalent.
218 uint32_t Gen32BitCvtCode(uint32_t value_id, InstructionBuilder* builder);
219
220 // Generate code to cast integer |value_id| to 32bit unsigned, if needed.
221 // Return an id to the Uint equivalent.
222 uint32_t GenUintCastCode(uint32_t value_id, InstructionBuilder* builder);
223
224 // Return new label.
225 std::unique_ptr<Instruction> NewLabel(uint32_t label_id);
226
227 // Return id for 32-bit unsigned type
228 uint32_t GetUintId();
229
230 // Return id for 64-bit unsigned type
231 uint32_t GetUint64Id();
232
233 // Return id for 8-bit unsigned type
234 uint32_t GetUint8Id();
235
236 // Return id for 32-bit unsigned type
237 uint32_t GetBoolId();
238
239 // Return id for void type
240 uint32_t GetVoidId();
241
242 // Return pointer to type for runtime array of uint
243 analysis::Type* GetUintXRuntimeArrayType(uint32_t width,
244 analysis::Type** rarr_ty);
245
246 // Return pointer to type for runtime array of uint
247 analysis::Type* GetUintRuntimeArrayType(uint32_t width);
248
249 // Return id for buffer uint type
250 uint32_t GetOutputBufferPtrId();
251
252 // Return id for buffer uint type
253 uint32_t GetInputBufferTypeId();
254
255 // Return id for buffer uint type
256 uint32_t GetInputBufferPtrId();
257
258 // Return binding for output buffer for current validation.
259 uint32_t GetOutputBufferBinding();
260
261 // Return binding for input buffer for current validation.
262 uint32_t GetInputBufferBinding();
263
264 // Add storage buffer extension if needed
265 void AddStorageBufferExt();
266
267 // Return id for debug output buffer
268 uint32_t GetOutputBufferId();
269
270 // Return id for debug input buffer
271 uint32_t GetInputBufferId();
272
273 // Return id for 32-bit float type
274 uint32_t GetFloatId();
275
276 // Return id for v4float type
277 uint32_t GetVec4FloatId();
278
279 // Return id for uint vector type of |length|
280 uint32_t GetVecUintId(uint32_t length);
281
282 // Return id for v4uint type
283 uint32_t GetVec4UintId();
284
285 // Return id for v3uint type
286 uint32_t GetVec3UintId();
287
288 // Return id for output function. Define if it doesn't exist with
289 // |val_spec_param_cnt| validation-specific uint32 parameters.
290 uint32_t GetStreamWriteFunctionId(uint32_t stage_idx,
291 uint32_t val_spec_param_cnt);
292
293 // Return id for input function taking |param_cnt| uint32 parameters. Define
294 // if it doesn't exist.
295 uint32_t GetDirectReadFunctionId(uint32_t param_cnt);
296
297 // Split block |block_itr| into two new blocks where the second block
298 // contains |inst_itr| and place in |new_blocks|.
299 void SplitBlock(BasicBlock::iterator inst_itr,
300 UptrVectorIterator<BasicBlock> block_itr,
301 std::vector<std::unique_ptr<BasicBlock>>* new_blocks);
302
303 // Apply instrumentation function |pfn| to every instruction in |func|.
304 // If code is generated for an instruction, replace the instruction's
305 // block with the new blocks that are generated. Continue processing at the
306 // top of the last new block.
307 bool InstrumentFunction(Function* func, uint32_t stage_idx,
308 InstProcessFunction& pfn);
309
310 // Call |pfn| on all functions in the call tree of the function
311 // ids in |roots|.
312 bool InstProcessCallTreeFromRoots(InstProcessFunction& pfn,
313 std::queue<uint32_t>* roots,
314 uint32_t stage_idx);
315
316 // Gen code into |builder| to write |field_value_id| into debug output
317 // buffer at |base_offset_id| + |field_offset|.
318 void GenDebugOutputFieldCode(uint32_t base_offset_id, uint32_t field_offset,
319 uint32_t field_value_id,
320 InstructionBuilder* builder);
321
322 // Generate instructions into |builder| which will write the members
323 // of the debug output record common for all stages and validations at
324 // |base_off|.
325 void GenCommonStreamWriteCode(uint32_t record_sz, uint32_t instruction_idx,
326 uint32_t stage_idx, uint32_t base_off,
327 InstructionBuilder* builder);
328
329 // Generate instructions into |builder| which will write
330 // |uint_frag_coord_id| at |component| of the record at |base_offset_id| of
331 // the debug output buffer .
332 void GenFragCoordEltDebugOutputCode(uint32_t base_offset_id,
333 uint32_t uint_frag_coord_id,
334 uint32_t component,
335 InstructionBuilder* builder);
336
337 // Generate instructions into |builder| which will load |var_id| and return
338 // its result id.
339 uint32_t GenVarLoad(uint32_t var_id, InstructionBuilder* builder);
340
341 // Generate instructions into |builder| which will load the uint |builtin_id|
342 // and write it into the debug output buffer at |base_off| + |builtin_off|.
343 void GenBuiltinOutputCode(uint32_t builtin_id, uint32_t builtin_off,
344 uint32_t base_off, InstructionBuilder* builder);
345
346 // Generate instructions into |builder| which will write the |stage_idx|-
347 // specific members of the debug output stream at |base_off|.
348 void GenStageStreamWriteCode(uint32_t stage_idx, uint32_t base_off,
349 InstructionBuilder* builder);
350
351 // Return true if instruction must be in the same block that its result
352 // is used.
353 bool IsSameBlockOp(const Instruction* inst) const;
354
355 // Clone operands which must be in same block as consumer instructions.
356 // Look in same_blk_pre for instructions that need cloning. Look in
357 // same_blk_post for instructions already cloned. Add cloned instruction
358 // to same_blk_post.
359 void CloneSameBlockOps(
360 std::unique_ptr<Instruction>* inst,
361 std::unordered_map<uint32_t, uint32_t>* same_blk_post,
362 std::unordered_map<uint32_t, Instruction*>* same_blk_pre,
363 BasicBlock* block_ptr);
364
365 // Update phis in succeeding blocks to point to new last block
366 void UpdateSucceedingPhis(
367 std::vector<std::unique_ptr<BasicBlock>>& new_blocks);
368
369 // Debug descriptor set index
370 uint32_t desc_set_;
371
372 // Shader module ID written into output record
373 uint32_t shader_id_;
374
375 // Map from function id to function pointer.
376 std::unordered_map<uint32_t, Function*> id2function_;
377
378 // Map from block's label id to block. TODO(dnovillo): This is superfluous wrt
379 // CFG. It has functionality not present in CFG. Consolidate.
380 std::unordered_map<uint32_t, BasicBlock*> id2block_;
381
382 // Map from instruction's unique id to offset in original file.
383 std::unordered_map<uint32_t, uint32_t> uid2offset_;
384
385 // result id for OpConstantFalse
386 uint32_t validation_id_;
387
388 // id for output buffer variable
389 uint32_t output_buffer_id_;
390
391 // ptr type id for output buffer element
392 uint32_t output_buffer_ptr_id_;
393
394 // ptr type id for input buffer element
395 uint32_t input_buffer_ptr_id_;
396
397 // id for debug output function
398 std::unordered_map<uint32_t, uint32_t> param2output_func_id_;
399
400 // ids for debug input functions
401 std::unordered_map<uint32_t, uint32_t> param2input_func_id_;
402
403 // id for input buffer variable
404 uint32_t input_buffer_id_;
405
406 // id for 32-bit float type
407 uint32_t float_id_;
408
409 // id for v4float type
410 uint32_t v4float_id_;
411
412 // id for v4uint type
413 uint32_t v4uint_id_;
414
415 // id for v3uint type
416 uint32_t v3uint_id_;
417
418 // id for 32-bit unsigned type
419 uint32_t uint_id_;
420
421 // id for 64-bit unsigned type
422 uint32_t uint64_id_;
423
424 // id for 8-bit unsigned type
425 uint32_t uint8_id_;
426
427 // id for bool type
428 uint32_t bool_id_;
429
430 // id for void type
431 uint32_t void_id_;
432
433 // boolean to remember storage buffer extension
434 bool storage_buffer_ext_defined_;
435
436 // runtime array of uint type
437 analysis::Type* uint64_rarr_ty_;
438
439 // runtime array of uint type
440 analysis::Type* uint32_rarr_ty_;
441
442 // Pre-instrumentation same-block insts
443 std::unordered_map<uint32_t, Instruction*> same_block_pre_;
444
445 // Post-instrumentation same-block op ids
446 std::unordered_map<uint32_t, uint32_t> same_block_post_;
447
448 // Map function calls to result id. Clear for every function.
449 // This is for debug input reads with constant arguments that
450 // have been generated into the first block of the function.
451 // This mechanism is used to avoid multiple identical debug
452 // input buffer reads.
453 struct vector_hash_ {
454 std::size_t operator()(const std::vector<uint32_t>& v) const {
455 std::size_t hash = v.size();
456 for (auto& u : v) {
457 hash ^= u + 0x9e3779b9 + (hash << 11) + (hash >> 21);
458 }
459 return hash;
460 }
461 };
462 std::unordered_map<std::vector<uint32_t>, uint32_t, vector_hash_> call2id_;
463
464 // Function currently being instrumented
465 Function* curr_func_;
466
467 // Optimize direct debug input buffer reads. Specifically, move all such
468 // reads with constant args to first block and reuse them.
469 bool opt_direct_reads_;
470 };
471
472 } // namespace opt
473 } // namespace spvtools
474
475 #endif // LIBSPIRV_OPT_INSTRUMENT_PASS_H_