Coverage Report

Created: 2025-06-13 06:49

/src/spirv-tools/source/name_mapper.h
Line
Count
Source
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
373k
  NameMapper GetNameMapper() {
73
25.5M
    return [this](uint32_t id) { return this->NameForId(id); };
74
373k
  }
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
22.2M
      void* user_data, const spv_parsed_instruction_t* parsed_instruction) {
104
22.2M
    return reinterpret_cast<FriendlyNameMapper*>(user_data)->ParseInstruction(
105
22.2M
        *parsed_instruction);
106
22.2M
  }
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_