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 GetPreservedAnalyses()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) Pass()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_ { operatorvector_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_ 476