source/name_mapper.h

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