1 // 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 LIBSPIRV_NAME_MAPPER_H_ 16 #define LIBSPIRV_NAME_MAPPER_H_ 17 18 #include <functional> 19 #include <string> 20 #include <unordered_map> 21 #include <unordered_set> 22 23 #include "spirv-tools/libspirv.h" 24 #include "assembly_grammar.h" 25 26 namespace libspirv { 27 28 // A NameMapper maps SPIR-V Id values to names. Each name is valid to use in 29 // SPIR-V assembly. The mapping is one-to-one, i.e. no two Ids map to the same 30 // name. 31 using NameMapper = std::function<std::string(uint32_t)>; 32 33 // Returns a NameMapper which always maps an Id to its decimal representation. 34 NameMapper GetTrivialNameMapper(); 35 36 // A FriendlyNameMapper parses a module upon construction. If the parse is 37 // successful, then the NameForId method maps an Id to a friendly name 38 // while also satisfying the constraints on a NameMapper. 39 // 40 // The mapping is friendly in the following sense: 41 // - If an Id has a debug name (via OpName), then that will be used when 42 // possible. 43 // - Well known scalar types map to friendly names. For example, 44 // OpTypeVoid should be %void. Scalar types map to their names in OpenCL when 45 // there is a correspondence, and otherwise as follows: 46 // - unsigned integer type of n bits map to "u" followed by n 47 // - signed integer type of n bits map to "i" followed by n 48 // - floating point type of n bits map to "fp" followed by n 49 // - Vector type names map to "v" followed by the number of components, 50 // followed by the friendly name for the base type. 51 // - Matrix type names map to "mat" followed by the number of columns, 52 // followed by the friendly name for the base vector type. 53 // - Pointer types map to "_ptr_", then the name of the storage class, then the 54 // name for the pointee type. 55 // - Exotic types like event, pipe, opaque, queue, reserve-id map to their own 56 // human readable names. 57 // - A struct type maps to "_struct_" followed by the raw Id number. That's 58 // pretty simplistic, but workable. 59 // - A built-in variable maps to its GLSL variable name. 60 // - Numeric literals in OpConstant map to a human-friendly name. 61 class FriendlyNameMapper { 62 public: 63 // Construct a friendly name mapper, and determine friendly names for each 64 // defined Id in the specified module. The module is specified by the code 65 // wordCount, and should be parseable in the specified context. 66 FriendlyNameMapper(const spv_const_context context, const uint32_t* code, 67 const size_t wordCount); 68 69 // Returns a NameMapper which maps ids to the friendly names parsed from the 70 // module provided to the constructor. GetNameMapper()71 NameMapper GetNameMapper() { 72 return [this](uint32_t id) { return this->NameForId(id); }; 73 } 74 75 // Returns the friendly name for the given id. If the module parsed during 76 // construction is valid, then the mapping satisfies the rules for a 77 // NameMapper. 78 std::string NameForId(uint32_t id); 79 80 private: 81 // Transforms the given string so that it is acceptable as an Id name in 82 // assembly language. Two distinct inputs can map to the same output. 83 std::string Sanitize(const std::string& suggested_name); 84 85 // Records a name for the given id. If this id already has a name, then 86 // this is a no-op. If the id doesn't have a name, use the given 87 // suggested_name if it hasn't already been taken, and otherwise generate 88 // a new (unused) name based on the suggested name. 89 void SaveName(uint32_t id, const std::string& suggested_name); 90 91 // Records a built-in variable name for target_id. If target_id already 92 // has a name then this is a no-op. 93 void SaveBuiltInName(uint32_t target_id, uint32_t built_in); 94 95 // Collects information from the given parsed instruction to populate 96 // name_for_id_. Returns SPV_SUCCESS; 97 spv_result_t ParseInstruction(const spv_parsed_instruction_t& inst); 98 99 // Forwards a parsed-instruction callback from the binary parser into the 100 // FriendlyNameMapper hidden inside the user_data parameter. ParseInstructionForwarder(void * user_data,const spv_parsed_instruction_t * parsed_instruction)101 static spv_result_t ParseInstructionForwarder( 102 void* user_data, const spv_parsed_instruction_t* parsed_instruction) { 103 return reinterpret_cast<FriendlyNameMapper*>(user_data)->ParseInstruction( 104 *parsed_instruction); 105 } 106 107 // Returns the friendly name for an enumerant. 108 std::string NameForEnumOperand(spv_operand_type_t type, uint32_t word); 109 110 // Maps an id to its friendly name. This will have an entry for each Id 111 // defined in the module. 112 std::unordered_map<uint32_t, std::string> name_for_id_; 113 // The set of names that have a mapping in name_for_id_; 114 std::unordered_set<std::string> used_names_; 115 // The assembly grammar for the current context. 116 const libspirv::AssemblyGrammar grammar_; 117 }; 118 119 } // namespace libspirv 120 121 #endif // _LIBSPIRV_NAME_MAPPER_H_ 122