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 64 class InstrumentPass : public Pass { 65 using cbb_ptr = const BasicBlock*; 66 67 public: 68 using InstProcessFunction = std::function<void( 69 BasicBlock::iterator, UptrVectorIterator<BasicBlock>, uint32_t, uint32_t, 70 std::vector<std::unique_ptr<BasicBlock>>*)>; 71 72 ~InstrumentPass() override = default; 73 74 IRContext::Analysis GetPreservedAnalyses() override { 75 return IRContext::kAnalysisDefUse | 76 IRContext::kAnalysisInstrToBlockMapping | 77 IRContext::kAnalysisDecorations | IRContext::kAnalysisCombinators | 78 IRContext::kAnalysisNameMap | IRContext::kAnalysisBuiltinVarId | 79 IRContext::kAnalysisConstants | IRContext::kAnalysisTypes; 80 } 81 82 protected: 83 // Create instrumentation pass which utilizes descriptor set |desc_set| 84 // for debug input and output buffers and writes |shader_id| into debug 85 // output records. 86 InstrumentPass(uint32_t desc_set, uint32_t shader_id, uint32_t validation_id) 87 : Pass(), 88 desc_set_(desc_set), 89 shader_id_(shader_id), 90 validation_id_(validation_id) {} 91 92 // Initialize state for instrumentation of module by |validation_id|. 93 void InitializeInstrument(); 94 95 // Call |pfn| on all instructions in all functions in the call tree of the 96 // entry points in |module|. If code is generated for an instruction, replace 97 // the instruction's block with the new blocks that are generated. Continue 98 // processing at the top of the last new block. 99 bool InstProcessEntryPointCallTree(InstProcessFunction& pfn); 100 101 // Move all code in |ref_block_itr| preceding the instruction |ref_inst_itr| 102 // to be instrumented into block |new_blk_ptr|. 103 void MovePreludeCode(BasicBlock::iterator ref_inst_itr, 104 UptrVectorIterator<BasicBlock> ref_block_itr, 105 std::unique_ptr<BasicBlock>* new_blk_ptr); 106 107 // Move all code in |ref_block_itr| succeeding the instruction |ref_inst_itr| 108 // to be instrumented into block |new_blk_ptr|. 109 void MovePostludeCode(UptrVectorIterator<BasicBlock> ref_block_itr, 110 std::unique_ptr<BasicBlock>* new_blk_ptr); 111 112 // Generate instructions in |builder| which will atomically fetch and 113 // increment the size of the debug output buffer stream of the current 114 // validation and write a record to the end of the stream, if enough space 115 // in the buffer remains. The record will contain the index of the function 116 // and instruction within that function |func_idx, instruction_idx| which 117 // generated the record. It will also contain additional information to 118 // identify the instance of the shader, depending on the stage |stage_idx| 119 // of the shader. Finally, the record will contain validation-specific 120 // data contained in |validation_ids| which will identify the validation 121 // error as well as the values involved in the error. 122 // 123 // The output buffer binding written to by the code generated by the function 124 // is determined by the validation id specified when each specific 125 // instrumentation pass is created. 126 // 127 // The output buffer is a sequence of 32-bit values with the following 128 // format (where all elements are unsigned 32-bit unless otherwise noted): 129 // 130 // Size 131 // Record0 132 // Record1 133 // Record2 134 // ... 135 // 136 // Size is the number of 32-bit values that have been written or 137 // attempted to be written to the output buffer, excluding the Size. It is 138 // initialized to 0. If the size of attempts to write the buffer exceeds 139 // the actual size of the buffer, it is possible that this field can exceed 140 // the actual size of the buffer. 141 // 142 // Each Record* is a variable-length sequence of 32-bit values with the 143 // following format defined using static const offsets in the .cpp file: 144 // 145 // Record Size 146 // Shader ID 147 // Instruction Index 148 // Stage 149 // Stage-specific Word 0 150 // Stage-specific Word 1 151 // Validation Error Code 152 // Validation-specific Word 0 153 // Validation-specific Word 1 154 // Validation-specific Word 2 155 // ... 156 // 157 // Each record consists of three subsections: members common across all 158 // validation, members specific to the stage, and members specific to a 159 // validation. 160 // 161 // The Record Size is the number of 32-bit words in the record, including 162 // the Record Size word. 163 // 164 // Shader ID is a value that identifies which shader has generated the 165 // validation error. It is passed when the instrumentation pass is created. 166 // 167 // The Instruction Index is the position of the instruction within the 168 // SPIR-V file which is in error. 169 // 170 // The Stage is the pipeline stage which has generated the error as defined 171 // by the SpvExecutionModel_ enumeration. This is used to interpret the 172 // following Stage-specific words. 173 // 174 // The Stage-specific Words identify which invocation of the shader generated 175 // the error. Every stage will write two words, although in some cases the 176 // second word is unused and so zero is written. Vertex shaders will write 177 // the Vertex and Instance ID. Fragment shaders will write FragCoord.xy. 178 // Compute shaders will write the Global Invocation ID and zero (unused). 179 // Both tesselation shaders will write the Invocation Id and zero (unused). 180 // The geometry shader will write the Primitive ID and Invocation ID. 181 // 182 // The Validation Error Code specifies the exact error which has occurred. 183 // These are enumerated with the kInstError* static consts. This allows 184 // multiple validation layers to use the same, single output buffer. 185 // 186 // The Validation-specific Words are a validation-specific number of 32-bit 187 // words which give further information on the validation error that 188 // occurred. These are documented further in each file containing the 189 // validation-specific class which derives from this base class. 190 // 191 // Because the code that is generated checks against the size of the buffer 192 // before writing, the size of the debug out buffer can be used by the 193 // validation layer to control the number of error records that are written. 194 void GenDebugStreamWrite(uint32_t instruction_idx, uint32_t stage_idx, 195 const std::vector<uint32_t>& validation_ids, 196 InstructionBuilder* builder); 197 198 // Generate code to cast |value_id| to unsigned, if needed. Return 199 // an id to the unsigned equivalent. 200 uint32_t GenUintCastCode(uint32_t value_id, InstructionBuilder* builder); 201 202 // Return new label. 203 std::unique_ptr<Instruction> NewLabel(uint32_t label_id); 204 205 // Return id for 32-bit unsigned type 206 uint32_t GetUintId(); 207 208 // Return id for 32-bit unsigned type 209 uint32_t GetBoolId(); 210 211 // Return id for void type 212 uint32_t GetVoidId(); 213 214 // Return id for output buffer uint type 215 uint32_t GetOutputBufferUintPtrId(); 216 217 // Return binding for output buffer for current validation. 218 uint32_t GetOutputBufferBinding(); 219 220 // Return id for debug output buffer 221 uint32_t GetOutputBufferId(); 222 223 // Return id for v4float type 224 uint32_t GetVec4FloatId(); 225 226 // Return id for v4uint type 227 uint32_t GetVec4UintId(); 228 229 // Return id for output function. Define if it doesn't exist with 230 // |val_spec_arg_cnt| validation-specific uint32 arguments. 231 uint32_t GetStreamWriteFunctionId(uint32_t stage_idx, 232 uint32_t val_spec_param_cnt); 233 234 // Apply instrumentation function |pfn| to every instruction in |func|. 235 // If code is generated for an instruction, replace the instruction's 236 // block with the new blocks that are generated. Continue processing at the 237 // top of the last new block. 238 bool InstrumentFunction(Function* func, uint32_t stage_idx, 239 InstProcessFunction& pfn); 240 241 // Call |pfn| on all functions in the call tree of the function 242 // ids in |roots|. 243 bool InstProcessCallTreeFromRoots(InstProcessFunction& pfn, 244 std::queue<uint32_t>* roots, 245 uint32_t stage_idx); 246 247 // Gen code into |builder| to write |field_value_id| into debug output 248 // buffer at |base_offset_id| + |field_offset|. 249 void GenDebugOutputFieldCode(uint32_t base_offset_id, uint32_t field_offset, 250 uint32_t field_value_id, 251 InstructionBuilder* builder); 252 253 // Generate instructions into |builder| which will write the members 254 // of the debug output record common for all stages and validations at 255 // |base_off|. 256 void GenCommonStreamWriteCode(uint32_t record_sz, uint32_t instruction_idx, 257 uint32_t stage_idx, uint32_t base_off, 258 InstructionBuilder* builder); 259 260 // Generate instructions into |builder| which will write 261 // |uint_frag_coord_id| at |component| of the record at |base_offset_id| of 262 // the debug output buffer . 263 void GenFragCoordEltDebugOutputCode(uint32_t base_offset_id, 264 uint32_t uint_frag_coord_id, 265 uint32_t component, 266 InstructionBuilder* builder); 267 268 // Generate instructions into |builder| which will load the uint |builtin_id| 269 // and write it into the debug output buffer at |base_off| + |builtin_off|. 270 void GenBuiltinOutputCode(uint32_t builtin_id, uint32_t builtin_off, 271 uint32_t base_off, InstructionBuilder* builder); 272 273 // Generate instructions into |builder| which will write a uint null into 274 // the debug output buffer at |base_off| + |builtin_off|. 275 void GenUintNullOutputCode(uint32_t field_off, uint32_t base_off, 276 InstructionBuilder* builder); 277 278 // Generate instructions into |builder| which will write the |stage_idx|- 279 // specific members of the debug output stream at |base_off|. 280 void GenStageStreamWriteCode(uint32_t stage_idx, uint32_t base_off, 281 InstructionBuilder* builder); 282 283 // Return true if instruction must be in the same block that its result 284 // is used. 285 bool IsSameBlockOp(const Instruction* inst) const; 286 287 // Clone operands which must be in same block as consumer instructions. 288 // Look in same_blk_pre for instructions that need cloning. Look in 289 // same_blk_post for instructions already cloned. Add cloned instruction 290 // to same_blk_post. 291 void CloneSameBlockOps( 292 std::unique_ptr<Instruction>* inst, 293 std::unordered_map<uint32_t, uint32_t>* same_blk_post, 294 std::unordered_map<uint32_t, Instruction*>* same_blk_pre, 295 std::unique_ptr<BasicBlock>* block_ptr); 296 297 // Update phis in succeeding blocks to point to new last block 298 void UpdateSucceedingPhis( 299 std::vector<std::unique_ptr<BasicBlock>>& new_blocks); 300 301 // Debug descriptor set index 302 uint32_t desc_set_; 303 304 // Shader module ID written into output record 305 uint32_t shader_id_; 306 307 // Map from function id to function pointer. 308 std::unordered_map<uint32_t, Function*> id2function_; 309 310 // Map from block's label id to block. TODO(dnovillo): This is superfluous wrt 311 // CFG. It has functionality not present in CFG. Consolidate. 312 std::unordered_map<uint32_t, BasicBlock*> id2block_; 313 314 // Map from function's position index to the offset of its first instruction 315 std::unordered_map<uint32_t, uint32_t> funcIdx2offset_; 316 317 // result id for OpConstantFalse 318 uint32_t validation_id_; 319 320 // id for output buffer variable 321 uint32_t output_buffer_id_; 322 323 // type id for output buffer element 324 uint32_t output_buffer_uint_ptr_id_; 325 326 // id for debug output function 327 uint32_t output_func_id_; 328 329 // param count for output function 330 uint32_t output_func_param_cnt_; 331 332 // id for v4float type 333 uint32_t v4float_id_; 334 335 // id for v4float type 336 uint32_t v4uint_id_; 337 338 // id for 32-bit unsigned type 339 uint32_t uint_id_; 340 341 // id for bool type 342 uint32_t bool_id_; 343 344 // id for void type 345 uint32_t void_id_; 346 347 // Pre-instrumentation same-block insts 348 std::unordered_map<uint32_t, Instruction*> same_block_pre_; 349 350 // Post-instrumentation same-block op ids 351 std::unordered_map<uint32_t, uint32_t> same_block_post_; 352 }; 353 354 } // namespace opt 355 } // namespace spvtools 356 357 #endif // LIBSPIRV_OPT_INSTRUMENT_PASS_H_ 358