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
 160     OperandOpcode,
 161
 162     OperandCount
 163 };
 164
 165 // Any specific enum can have a set of capabilities that allow it:
 166 typedef std::vector<Capability> EnumCaps;
 167
 168 // Parameterize a set of operands with their OperandClass(es) and descriptions.
 169 class OperandParameters {
 170 public:
 171     OperandParameters() { }
 172     void push(OperandClass oc, const char* d, bool opt = false)
 173     {
 174         opClass.push_back(oc);
 175         desc.push_back(d);
 176         optional.push_back(opt);
 177     }
 178     void setOptional();
 179     OperandClass getClass(int op) const { return opClass[op]; }
 180     const char* getDesc(int op) const { return desc[op]; }
 181     bool isOptional(int op) const { return optional[op]; }
 182     int getNum() const { return (int)opClass.size(); }
 183
 184 protected:
 185     std::vector<OperandClass> opClass;
 186     std::vector<const char*> desc;
 187     std::vector<bool> optional;
 188 };
 189
 190 // Parameterize an enumerant
 191 class EnumParameters {
 192 public:
 193     EnumParameters() : desc(0) { }
 194     const char* desc;
 195 };
 196
 197 // Parameterize a set of enumerants that form an enum
 198 class EnumDefinition : public EnumParameters {
 199 public:
 200     EnumDefinition() :
 201         ceiling(0), bitmask(false), getName(0), enumParams(0), operandParams(0) { }
 202     void set(int ceil, const char* (*name)(int), EnumParameters* ep, bool mask = false)
 203     {
 204         ceiling = ceil;
 205         getName = name;
 206         bitmask = mask;
 207         enumParams = ep;
 208     }
 209     void setOperands(OperandParameters* op) { operandParams = op; }
 210     int ceiling;   // ceiling of enumerants
 211     bool bitmask;  // true if these enumerants combine into a bitmask
 212     const char* (*getName)(int);      // a function that returns the name for each enumerant value (or shift)
 213     EnumParameters* enumParams;       // parameters for each individual enumerant
 214     OperandParameters* operandParams; // sets of operands
 215 };
 216
 217 // Parameterize an instruction's logical format, including its known set of operands,
 218 // per OperandParameters above.
 219 class InstructionParameters {
 220 public:
 221     InstructionParameters() :
 222         opDesc("TBD"),
 223         opClass(OpClassMissing),
 224         typePresent(true),         // most normal, only exceptions have to be spelled out
 225         resultPresent(true)        // most normal, only exceptions have to be spelled out
 226     { }
 227
 228     void setResultAndType(bool r, bool t)
 229     {
 230         resultPresent = r;
 231         typePresent = t;
 232     }
 233
 234     bool hasResult() const { return resultPresent != 0; }
 235     bool hasType()   const { return typePresent != 0; }
 236
 237     const char* opDesc;
 238     OpcodeClass opClass;
 239     OperandParameters operands;
 240
 241 protected:
 242     int typePresent   : 1;
 243     int resultPresent : 1;
 244 };
 245
 246 // The set of objects that hold all the instruction/operand
 247 // parameterization information.
 248 extern InstructionParameters InstructionDesc[];
 249
 250 // These hold definitions of the enumerants used for operands
 251 extern EnumDefinition OperandClassParams[];
 252
 253 const char* GetOperandDesc(OperandClass operand);
 254 void PrintImmediateRow(int imm, const char* name, const EnumParameters* enumParams, bool caps, bool hex = false);
 255 const char* AccessQualifierString(int attr);
 256
 257 void PrintOperands(const OperandParameters& operands, int reservedOperands);
 258
 259 }  // end namespace spv