1 // Copyright (c) 2020 The Khronos Group Inc. 2 // Copyright (c) 2020 Valve Corporation 3 // Copyright (c) 2020 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_INST_DEBUG_PRINTF_PASS_H_ 18 #define LIBSPIRV_OPT_INST_DEBUG_PRINTF_PASS_H_ 19 20 #include "instrument_pass.h" 21 22 namespace spvtools { 23 namespace opt { 24 25 // This class/pass is designed to support the debug printf GPU-assisted layer 26 // of https://github.com/KhronosGroup/Vulkan-ValidationLayers. Its internal and 27 // external design may change as the layer evolves. 28 class InstDebugPrintfPass : public InstrumentPass { 29 public: 30 // For test harness only InstDebugPrintfPass()31 InstDebugPrintfPass() : InstrumentPass(7, 23, false, false) {} 32 // For all other interfaces InstDebugPrintfPass(uint32_t desc_set,uint32_t shader_id)33 InstDebugPrintfPass(uint32_t desc_set, uint32_t shader_id) 34 : InstrumentPass(desc_set, shader_id, false, false) {} 35 36 ~InstDebugPrintfPass() override = default; 37 38 // See optimizer.hpp for pass user documentation. 39 Status Process() override; 40 name()41 const char* name() const override { return "inst-printf-pass"; } 42 43 private: 44 // Gen code into |builder| to write |field_value_id| into debug output 45 // buffer at |base_offset_id| + |field_offset|. 46 void GenDebugOutputFieldCode(uint32_t base_offset_id, uint32_t field_offset, 47 uint32_t field_value_id, 48 InstructionBuilder* builder); 49 50 // Generate instructions in |builder| which will atomically fetch and 51 // increment the size of the debug output buffer stream of the current 52 // validation and write a record to the end of the stream, if enough space 53 // in the buffer remains. The record will contain the index of the function 54 // and instruction within that function |func_idx, instruction_idx| which 55 // generated the record. Finally, the record will contain validation-specific 56 // data contained in |validation_ids| which will identify the validation 57 // error as well as the values involved in the error. 58 // 59 // The output buffer binding written to by the code generated by the function 60 // is determined by the validation id specified when each specific 61 // instrumentation pass is created. 62 // 63 // The output buffer is a sequence of 32-bit values with the following 64 // format (where all elements are unsigned 32-bit unless otherwise noted): 65 // 66 // Size 67 // Record0 68 // Record1 69 // Record2 70 // ... 71 // 72 // Size is the number of 32-bit values that have been written or 73 // attempted to be written to the output buffer, excluding the Size. It is 74 // initialized to 0. If the size of attempts to write the buffer exceeds 75 // the actual size of the buffer, it is possible that this field can exceed 76 // the actual size of the buffer. 77 // 78 // Each Record* is a variable-length sequence of 32-bit values with the 79 // following format defined using static const offsets in the .cpp file: 80 // 81 // Record Size 82 // Shader ID 83 // Instruction Index 84 // ... 85 // Validation Error Code 86 // Validation-specific Word 0 87 // Validation-specific Word 1 88 // Validation-specific Word 2 89 // ... 90 // 91 // Each record consists of two subsections: members common across all 92 // validation and members specific to a 93 // validation. 94 // 95 // The Record Size is the number of 32-bit words in the record, including 96 // the Record Size word. 97 // 98 // Shader ID is a value that identifies which shader has generated the 99 // validation error. It is passed when the instrumentation pass is created. 100 // 101 // The Instruction Index is the position of the instruction within the 102 // SPIR-V file which is in error. 103 // 104 // The Validation Error Code specifies the exact error which has occurred. 105 // These are enumerated with the kInstError* static consts. This allows 106 // multiple validation layers to use the same, single output buffer. 107 // 108 // The Validation-specific Words are a validation-specific number of 32-bit 109 // words which give further information on the validation error that 110 // occurred. These are documented further in each file containing the 111 // validation-specific class which derives from this base class. 112 // 113 // Because the code that is generated checks against the size of the buffer 114 // before writing, the size of the debug out buffer can be used by the 115 // validation layer to control the number of error records that are written. 116 void GenDebugStreamWrite(uint32_t shader_id, uint32_t instruction_idx_id, 117 const std::vector<uint32_t>& validation_ids, 118 InstructionBuilder* builder); 119 120 // Return id for output function. Define if it doesn't exist with 121 // |val_spec_param_cnt| validation-specific uint32 parameters. 122 uint32_t GetStreamWriteFunctionId(uint32_t val_spec_param_cnt); 123 124 // Generate instructions for OpDebugPrintf. 125 // 126 // If |ref_inst_itr| is an OpDebugPrintf, return in |new_blocks| the result 127 // of replacing it with buffer write instructions within its block at 128 // |ref_block_itr|. The instructions write a record to the printf 129 // output buffer stream including |function_idx, instruction_idx| 130 // and removes the OpDebugPrintf. The block at |ref_block_itr| can just be 131 // replaced with the block in |new_blocks|. Besides the buffer writes, this 132 // block will comprise all instructions preceding and following 133 // |ref_inst_itr|. 134 // 135 // This function is designed to be passed to 136 // InstrumentPass::InstProcessEntryPointCallTree(), which applies the 137 // function to each instruction in a module and replaces the instruction 138 // if warranted. 139 // 140 // This instrumentation function utilizes GenDebugStreamWrite() to write its 141 // error records. The validation-specific part of the error record will 142 // consist of a uint32 which is the id of the format string plus a sequence 143 // of uint32s representing the values of the remaining operands of the 144 // DebugPrintf. 145 void GenDebugPrintfCode(BasicBlock::iterator ref_inst_itr, 146 UptrVectorIterator<BasicBlock> ref_block_itr, 147 std::vector<std::unique_ptr<BasicBlock>>* new_blocks); 148 149 // Generate a sequence of uint32 instructions in |builder| (if necessary) 150 // representing the value of |val_inst|, which must be a buffer pointer, a 151 // uint64, or a scalar or vector of type uint32, float32 or float16. Append 152 // the ids of all values to the end of |val_ids|. 153 void GenOutputValues(Instruction* val_inst, std::vector<uint32_t>* val_ids, 154 InstructionBuilder* builder); 155 156 // Generate instructions to write a record containing the operands of 157 // |printf_inst| arguments to printf buffer, adding new code to the end of 158 // the last block in |new_blocks|. Kill OpDebugPrintf instruction. 159 void GenOutputCode(Instruction* printf_inst, 160 std::vector<std::unique_ptr<BasicBlock>>* new_blocks); 161 162 // Set the name for a function or global variable, names will be 163 // prefixed to identify which instrumentation pass generated them. 164 std::unique_ptr<Instruction> NewGlobalName(uint32_t id, 165 const std::string& name_str); 166 167 // Set the name for a structure member 168 std::unique_ptr<Instruction> NewMemberName(uint32_t id, uint32_t member_index, 169 const std::string& name_str); 170 171 // Return id for debug output buffer 172 uint32_t GetOutputBufferId(); 173 174 // Return id for buffer uint type 175 uint32_t GetOutputBufferPtrId(); 176 177 // Return binding for output buffer for current validation. 178 uint32_t GetOutputBufferBinding(); 179 180 // Initialize state for instrumenting bindless checking 181 void InitializeInstDebugPrintf(); 182 183 // Apply GenDebugPrintfCode to every instruction in module. 184 Pass::Status ProcessImpl(); 185 186 uint32_t ext_inst_printf_id_{0}; 187 188 // id for output buffer variable 189 uint32_t output_buffer_id_{0}; 190 191 // ptr type id for output buffer element 192 uint32_t output_buffer_ptr_id_{0}; 193 }; 194 195 } // namespace opt 196 } // namespace spvtools 197 198 #endif // LIBSPIRV_OPT_INST_DEBUG_PRINTF_PASS_H_ 199