SPIRV/doc.h

   1 //
   2 // Copyright (C) 2014-2015 LunarG, Inc.
   3 //
   4 // All rights reserved.
   5 //
   6 // Redistribution and use in source and binary forms, with or without
   7 // modification, are permitted provided that the following conditions
   8 // are met:
   9 //
  10 //    Redistributions of source code must retain the above copyright
  11 //    notice, this list of conditions and the following disclaimer.
  12 //
  13 //    Redistributions in binary form must reproduce the above
  14 //    copyright notice, this list of conditions and the following
  15 //    disclaimer in the documentation and/or other materials provided
  16 //    with the distribution.
  17 //
  18 //    Neither the name of 3Dlabs Inc. Ltd. nor the names of its
  19 //    contributors may be used to endorse or promote products derived
  20 //    from this software without specific prior written permission.
  21 //
  22 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  23 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  24 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  25 // FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  26 // COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  27 // INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  28 // BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  29 // LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  30 // CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 // LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  32 // ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  33 // POSSIBILITY OF SUCH DAMAGE.
  34
  35 //
  36 // Parameterize the SPIR-V enumerants.
  37 //
  38
  39 #pragma once
  40
  41 #include "spirv.hpp"
  42
  43 #include <vector>
  44
  45 namespace spv {
  46
  47 // Fill in all the parameters
  48 void Parameterize();
  49
  50 // Return the English names of all the enums.
  51 const char* SourceString(int);
  52 const char* AddressingString(int);
  53 const char* MemoryString(int);
  54 const char* ExecutionModelString(int);
  55 const char* ExecutionModeString(int);
  56 const char* StorageClassString(int);
  57 const char* DecorationString(int);
  58 const char* BuiltInString(int);
  59 const char* DimensionString(int);
  60 const char* SelectControlString(int);
  61 const char* LoopControlString(int);
  62 const char* FunctionControlString(int);
  63 const char* SamplerAddressingModeString(int);
  64 const char* SamplerFilterModeString(int);
  65 const char* ImageFormatString(int);
  66 const char* ImageChannelOrderString(int);
  67 const char* ImageChannelTypeString(int);
  68 const char* ImageChannelDataTypeString(int type);
  69 const char* ImageOperandsString(int format);
  70 const char* ImageOperands(int);
  71 const char* FPFastMathString(int);
  72 const char* FPRoundingModeString(int);
  73 const char* LinkageTypeString(int);
  74 const char* FuncParamAttrString(int);
  75 const char* AccessQualifierString(int);
  76 const char* MemorySemanticsString(int);
  77 const char* MemoryAccessString(int);
  78 const char* ExecutionScopeString(int);
  79 const char* GroupOperationString(int);
  80 const char* KernelEnqueueFlagsString(int);
  81 const char* KernelProfilingInfoString(int);
  82 const char* CapabilityString(int);
  83 const char* OpcodeString(int);
  84 const char* ScopeString(int mem);
  85
  86 // For grouping opcodes into subsections
  87 enum OpcodeClass {
  88     OpClassMisc,
  89     OpClassDebug,
  90     OpClassAnnotate,
  91     OpClassExtension,
  92     OpClassMode,
  93     OpClassType,
  94     OpClassConstant,
  95     OpClassMemory,
  96     OpClassFunction,
  97     OpClassImage,
  98     OpClassConvert,
  99     OpClassComposite,
 100     OpClassArithmetic,
 101     OpClassBit,
 102     OpClassRelationalLogical,
 103     OpClassDerivative,
 104     OpClassFlowControl,
 105     OpClassAtomic,
 106     OpClassPrimitive,
 107     OpClassBarrier,
 108     OpClassGroup,
 109     OpClassDeviceSideEnqueue,
 110     OpClassPipe,
 111
 112     OpClassCount,
 113     OpClassMissing             // all instructions start out as missing
 114 };
 115
 116 // For parameterizing operands.
 117 enum OperandClass {
 118     OperandNone,
 119     OperandId,
 120     OperandVariableIds,
 121     OperandOptionalLiteral,
 122     OperandOptionalLiteralString,
 123     OperandVariableLiterals,
 124     OperandVariableIdLiteral,
 125     OperandVariableLiteralId,
 126     OperandLiteralNumber,
 127     OperandLiteralString,
 128     OperandVariableLiteralStrings,
 129     OperandSource,
 130     OperandExecutionModel,
 131     OperandAddressing,
 132     OperandMemory,
 133     OperandExecutionMode,
 134     OperandStorage,
 135     OperandDimensionality,
 136     OperandSamplerAddressingMode,
 137     OperandSamplerFilterMode,
 138     OperandSamplerImageFormat,
 139     OperandImageChannelOrder,
 140     OperandImageChannelDataType,
 141     OperandImageOperands,
 142     OperandFPFastMath,
 143     OperandFPRoundingMode,
 144     OperandLinkageType,
 145     OperandAccessQualifier,
 146     OperandFuncParamAttr,
 147     OperandDecoration,
 148     OperandBuiltIn,
 149     OperandSelect,
 150     OperandLoop,
 151     OperandFunction,
 152     OperandMemorySemantics,
 153     OperandMemoryAccess,
 154     OperandScope,
 155     OperandGroupOperation,
 156     OperandKernelEnqueueFlags,
 157     OperandKernelProfilingInfo,
 158     OperandCapability,
 159     OperandCooperativeMatrixOperands,
 160     OperandTensorAddressingOperands,
 161
 162     OperandOpcode,
 163
 164     OperandCount
 165 };
 166
 167 // Any specific enum can have a set of capabilities that allow it:
 168 typedef std::vector<Capability> EnumCaps;
 169
 170 // Parameterize a set of operands with their OperandClass(es) and descriptions.
 171 class OperandParameters {
 172 public:
 173     OperandParameters() { }
 174     void push(OperandClass oc, const char* d, bool opt = false)
 175     {
 176         opClass.push_back(oc);
 177         desc.push_back(d);
 178         optional.push_back(opt);
 179     }
 180     void setOptional();
 181     OperandClass getClass(int op) const { return opClass[op]; }
 182     const char* getDesc(int op) const { return desc[op]; }
 183     bool isOptional(int op) const { return optional[op]; }
 184     int getNum() const { return (int)opClass.size(); }
 185
 186 protected:
 187     std::vector<OperandClass> opClass;
 188     std::vector<const char*> desc;
 189     std::vector<bool> optional;
 190 };
 191
 192 // Parameterize an enumerant
 193 class EnumParameters {
 194 public:
 195     EnumParameters() : desc(nullptr) { }
 196     const char* desc;
 197 };
 198
 199 // Parameterize a set of enumerants that form an enum
 200 class EnumDefinition : public EnumParameters {
 201 public:
 202     EnumDefinition() :
 203         ceiling(0), bitmask(false), getName(nullptr), enumParams(nullptr), operandParams(nullptr) { }
 204     void set(int ceil, const char* (*name)(int), EnumParameters* ep, bool mask = false)
 205     {
 206         ceiling = ceil;
 207         getName = name;
 208         bitmask = mask;
 209         enumParams = ep;
 210     }
 211     void setOperands(OperandParameters* op) { operandParams = op; }
 212     int ceiling;   // ceiling of enumerants
 213     bool bitmask;  // true if these enumerants combine into a bitmask
 214     const char* (*getName)(int);      // a function that returns the name for each enumerant value (or shift)
 215     EnumParameters* enumParams;       // parameters for each individual enumerant
 216     OperandParameters* operandParams; // sets of operands
 217 };
 218
 219 // Parameterize an instruction's logical format, including its known set of operands,
 220 // per OperandParameters above.
 221 class InstructionParameters {
 222 public:
 223     InstructionParameters() :
 224         opDesc("TBD"),
 225         opClass(OpClassMissing),
 226         typePresent(true),         // most normal, only exceptions have to be spelled out
 227         resultPresent(true)        // most normal, only exceptions have to be spelled out
 228     { }
 229
 230     void setResultAndType(bool r, bool t)
 231     {
 232         resultPresent = r;
 233         typePresent = t;
 234     }
 235
 236     bool hasResult() const { return resultPresent != 0; }
 237     bool hasType()   const { return typePresent != 0; }
 238
 239     const char* opDesc;
 240     OpcodeClass opClass;
 241     OperandParameters operands;
 242
 243 protected:
 244     bool typePresent   : 1;
 245     bool resultPresent : 1;
 246 };
 247
 248 // The set of objects that hold all the instruction/operand
 249 // parameterization information.
 250 extern InstructionParameters InstructionDesc[];
 251
 252 // These hold definitions of the enumerants used for operands
 253 extern EnumDefinition OperandClassParams[];
 254
 255 const char* GetOperandDesc(OperandClass operand);
 256 void PrintImmediateRow(int imm, const char* name, const EnumParameters* enumParams, bool caps, bool hex = false);
 257 const char* AccessQualifierString(int attr);
 258
 259 void PrintOperands(const OperandParameters& operands, int reservedOperands);
 260
 261 }  // end namespace spv