1 //===- DeserializeOps.cpp - MLIR SPIR-V Deserialization (Ops) -------------===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // This file defines the Deserializer methods for SPIR-V binary instructions.
10 //
11 //===----------------------------------------------------------------------===//
12 
13 #include "Deserializer.h"
14 
15 #include "mlir/Dialect/SPIRV/IR/SPIRVOps.h"
16 #include "mlir/IR/Builders.h"
17 #include "mlir/IR/Location.h"
18 #include "llvm/ADT/STLExtras.h"
19 #include "llvm/ADT/SmallVector.h"
20 #include "llvm/Support/Debug.h"
21 
22 using namespace mlir;
23 
24 #define DEBUG_TYPE "spirv-deserialization"
25 
26 //===----------------------------------------------------------------------===//
27 // Utility Functions
28 //===----------------------------------------------------------------------===//
29 
30 /// Extracts the opcode from the given first word of a SPIR-V instruction.
31 static inline spirv::Opcode extractOpcode(uint32_t word) {
32   return static_cast<spirv::Opcode>(word & 0xffff);
33 }
34 
35 //===----------------------------------------------------------------------===//
36 // Instruction
37 //===----------------------------------------------------------------------===//
38 
39 Value spirv::Deserializer::getValue(uint32_t id) {
40   if (auto constInfo = getConstant(id)) {
41     // Materialize a `spv.constant` op at every use site.
42     return opBuilder.create<spirv::ConstantOp>(unknownLoc, constInfo->second,
43                                                constInfo->first);
44   }
45   if (auto varOp = getGlobalVariable(id)) {
46     auto addressOfOp = opBuilder.create<spirv::AddressOfOp>(
47         unknownLoc, varOp.type(),
48         opBuilder.getSymbolRefAttr(varOp.getOperation()));
49     return addressOfOp.pointer();
50   }
51   if (auto constOp = getSpecConstant(id)) {
52     auto referenceOfOp = opBuilder.create<spirv::ReferenceOfOp>(
53         unknownLoc, constOp.default_value().getType(),
54         opBuilder.getSymbolRefAttr(constOp.getOperation()));
55     return referenceOfOp.reference();
56   }
57   if (auto constCompositeOp = getSpecConstantComposite(id)) {
58     auto referenceOfOp = opBuilder.create<spirv::ReferenceOfOp>(
59         unknownLoc, constCompositeOp.type(),
60         opBuilder.getSymbolRefAttr(constCompositeOp.getOperation()));
61     return referenceOfOp.reference();
62   }
63   if (auto specConstOperationInfo = getSpecConstantOperation(id)) {
64     return materializeSpecConstantOperation(
65         id, specConstOperationInfo->enclodesOpcode,
66         specConstOperationInfo->resultTypeID,
67         specConstOperationInfo->enclosedOpOperands);
68   }
69   if (auto undef = getUndefType(id)) {
70     return opBuilder.create<spirv::UndefOp>(unknownLoc, undef);
71   }
72   return valueMap.lookup(id);
73 }
74 
75 LogicalResult
76 spirv::Deserializer::sliceInstruction(spirv::Opcode &opcode,
77                                       ArrayRef<uint32_t> &operands,
78                                       Optional<spirv::Opcode> expectedOpcode) {
79   auto binarySize = binary.size();
80   if (curOffset >= binarySize) {
81     return emitError(unknownLoc, "expected ")
82            << (expectedOpcode ? spirv::stringifyOpcode(*expectedOpcode)
83                               : "more")
84            << " instruction";
85   }
86 
87   // For each instruction, get its word count from the first word to slice it
88   // from the stream properly, and then dispatch to the instruction handler.
89 
90   uint32_t wordCount = binary[curOffset] >> 16;
91 
92   if (wordCount == 0)
93     return emitError(unknownLoc, "word count cannot be zero");
94 
95   uint32_t nextOffset = curOffset + wordCount;
96   if (nextOffset > binarySize)
97     return emitError(unknownLoc, "insufficient words for the last instruction");
98 
99   opcode = extractOpcode(binary[curOffset]);
100   operands = binary.slice(curOffset + 1, wordCount - 1);
101   curOffset = nextOffset;
102   return success();
103 }
104 
105 LogicalResult spirv::Deserializer::processInstruction(
106     spirv::Opcode opcode, ArrayRef<uint32_t> operands, bool deferInstructions) {
107   LLVM_DEBUG(llvm::dbgs() << "[inst] processing instruction "
108                           << spirv::stringifyOpcode(opcode) << "\n");
109 
110   // First dispatch all the instructions whose opcode does not correspond to
111   // those that have a direct mirror in the SPIR-V dialect
112   switch (opcode) {
113   case spirv::Opcode::OpCapability:
114     return processCapability(operands);
115   case spirv::Opcode::OpExtension:
116     return processExtension(operands);
117   case spirv::Opcode::OpExtInst:
118     return processExtInst(operands);
119   case spirv::Opcode::OpExtInstImport:
120     return processExtInstImport(operands);
121   case spirv::Opcode::OpMemberName:
122     return processMemberName(operands);
123   case spirv::Opcode::OpMemoryModel:
124     return processMemoryModel(operands);
125   case spirv::Opcode::OpEntryPoint:
126   case spirv::Opcode::OpExecutionMode:
127     if (deferInstructions) {
128       deferredInstructions.emplace_back(opcode, operands);
129       return success();
130     }
131     break;
132   case spirv::Opcode::OpVariable:
133     if (isa<spirv::ModuleOp>(opBuilder.getBlock()->getParentOp())) {
134       return processGlobalVariable(operands);
135     }
136     break;
137   case spirv::Opcode::OpLine:
138     return processDebugLine(operands);
139   case spirv::Opcode::OpNoLine:
140     return clearDebugLine();
141   case spirv::Opcode::OpName:
142     return processName(operands);
143   case spirv::Opcode::OpString:
144     return processDebugString(operands);
145   case spirv::Opcode::OpModuleProcessed:
146   case spirv::Opcode::OpSource:
147   case spirv::Opcode::OpSourceContinued:
148   case spirv::Opcode::OpSourceExtension:
149     // TODO: This is debug information embedded in the binary which should be
150     // translated into the spv.module.
151     return success();
152   case spirv::Opcode::OpTypeVoid:
153   case spirv::Opcode::OpTypeBool:
154   case spirv::Opcode::OpTypeInt:
155   case spirv::Opcode::OpTypeFloat:
156   case spirv::Opcode::OpTypeVector:
157   case spirv::Opcode::OpTypeMatrix:
158   case spirv::Opcode::OpTypeArray:
159   case spirv::Opcode::OpTypeFunction:
160   case spirv::Opcode::OpTypeImage:
161   case spirv::Opcode::OpTypeRuntimeArray:
162   case spirv::Opcode::OpTypeStruct:
163   case spirv::Opcode::OpTypePointer:
164   case spirv::Opcode::OpTypeCooperativeMatrixNV:
165     return processType(opcode, operands);
166   case spirv::Opcode::OpTypeForwardPointer:
167     return processTypeForwardPointer(operands);
168   case spirv::Opcode::OpConstant:
169     return processConstant(operands, /*isSpec=*/false);
170   case spirv::Opcode::OpSpecConstant:
171     return processConstant(operands, /*isSpec=*/true);
172   case spirv::Opcode::OpConstantComposite:
173     return processConstantComposite(operands);
174   case spirv::Opcode::OpSpecConstantComposite:
175     return processSpecConstantComposite(operands);
176   case spirv::Opcode::OpSpecConstantOp:
177     return processSpecConstantOperation(operands);
178   case spirv::Opcode::OpConstantTrue:
179     return processConstantBool(/*isTrue=*/true, operands, /*isSpec=*/false);
180   case spirv::Opcode::OpSpecConstantTrue:
181     return processConstantBool(/*isTrue=*/true, operands, /*isSpec=*/true);
182   case spirv::Opcode::OpConstantFalse:
183     return processConstantBool(/*isTrue=*/false, operands, /*isSpec=*/false);
184   case spirv::Opcode::OpSpecConstantFalse:
185     return processConstantBool(/*isTrue=*/false, operands, /*isSpec=*/true);
186   case spirv::Opcode::OpConstantNull:
187     return processConstantNull(operands);
188   case spirv::Opcode::OpDecorate:
189     return processDecoration(operands);
190   case spirv::Opcode::OpMemberDecorate:
191     return processMemberDecoration(operands);
192   case spirv::Opcode::OpFunction:
193     return processFunction(operands);
194   case spirv::Opcode::OpLabel:
195     return processLabel(operands);
196   case spirv::Opcode::OpBranch:
197     return processBranch(operands);
198   case spirv::Opcode::OpBranchConditional:
199     return processBranchConditional(operands);
200   case spirv::Opcode::OpSelectionMerge:
201     return processSelectionMerge(operands);
202   case spirv::Opcode::OpLoopMerge:
203     return processLoopMerge(operands);
204   case spirv::Opcode::OpPhi:
205     return processPhi(operands);
206   case spirv::Opcode::OpUndef:
207     return processUndef(operands);
208   default:
209     break;
210   }
211   return dispatchToAutogenDeserialization(opcode, operands);
212 }
213 
214 LogicalResult spirv::Deserializer::processOpWithoutGrammarAttr(
215     ArrayRef<uint32_t> words, StringRef opName, bool hasResult,
216     unsigned numOperands) {
217   SmallVector<Type, 1> resultTypes;
218   uint32_t valueID = 0;
219 
220   size_t wordIndex = 0;
221   if (hasResult) {
222     if (wordIndex >= words.size())
223       return emitError(unknownLoc,
224                        "expected result type <id> while deserializing for ")
225              << opName;
226 
227     // Decode the type <id>
228     auto type = getType(words[wordIndex]);
229     if (!type)
230       return emitError(unknownLoc, "unknown type result <id>: ")
231              << words[wordIndex];
232     resultTypes.push_back(type);
233     ++wordIndex;
234 
235     // Decode the result <id>
236     if (wordIndex >= words.size())
237       return emitError(unknownLoc,
238                        "expected result <id> while deserializing for ")
239              << opName;
240     valueID = words[wordIndex];
241     ++wordIndex;
242   }
243 
244   SmallVector<Value, 4> operands;
245   SmallVector<NamedAttribute, 4> attributes;
246 
247   // Decode operands
248   size_t operandIndex = 0;
249   for (; operandIndex < numOperands && wordIndex < words.size();
250        ++operandIndex, ++wordIndex) {
251     auto arg = getValue(words[wordIndex]);
252     if (!arg)
253       return emitError(unknownLoc, "unknown result <id>: ") << words[wordIndex];
254     operands.push_back(arg);
255   }
256   if (operandIndex != numOperands) {
257     return emitError(
258                unknownLoc,
259                "found less operands than expected when deserializing for ")
260            << opName << "; only " << operandIndex << " of " << numOperands
261            << " processed";
262   }
263   if (wordIndex != words.size()) {
264     return emitError(
265                unknownLoc,
266                "found more operands than expected when deserializing for ")
267            << opName << "; only " << wordIndex << " of " << words.size()
268            << " processed";
269   }
270 
271   // Attach attributes from decorations
272   if (decorations.count(valueID)) {
273     auto attrs = decorations[valueID].getAttrs();
274     attributes.append(attrs.begin(), attrs.end());
275   }
276 
277   // Create the op and update bookkeeping maps
278   Location loc = createFileLineColLoc(opBuilder);
279   OperationState opState(loc, opName);
280   opState.addOperands(operands);
281   if (hasResult)
282     opState.addTypes(resultTypes);
283   opState.addAttributes(attributes);
284   Operation *op = opBuilder.createOperation(opState);
285   if (hasResult)
286     valueMap[valueID] = op->getResult(0);
287 
288   if (op->hasTrait<OpTrait::IsTerminator>())
289     clearDebugLine();
290 
291   return success();
292 }
293 
294 LogicalResult spirv::Deserializer::processUndef(ArrayRef<uint32_t> operands) {
295   if (operands.size() != 2) {
296     return emitError(unknownLoc, "OpUndef instruction must have two operands");
297   }
298   auto type = getType(operands[0]);
299   if (!type) {
300     return emitError(unknownLoc, "unknown type <id> with OpUndef instruction");
301   }
302   undefMap[operands[1]] = type;
303   return success();
304 }
305 
306 LogicalResult spirv::Deserializer::processExtInst(ArrayRef<uint32_t> operands) {
307   if (operands.size() < 4) {
308     return emitError(unknownLoc,
309                      "OpExtInst must have at least 4 operands, result type "
310                      "<id>, result <id>, set <id> and instruction opcode");
311   }
312   if (!extendedInstSets.count(operands[2])) {
313     return emitError(unknownLoc, "undefined set <id> in OpExtInst");
314   }
315   SmallVector<uint32_t, 4> slicedOperands;
316   slicedOperands.append(operands.begin(), std::next(operands.begin(), 2));
317   slicedOperands.append(std::next(operands.begin(), 4), operands.end());
318   return dispatchToExtensionSetAutogenDeserialization(
319       extendedInstSets[operands[2]], operands[3], slicedOperands);
320 }
321 
322 namespace mlir {
323 namespace spirv {
324 
325 template <>
326 LogicalResult
327 Deserializer::processOp<spirv::EntryPointOp>(ArrayRef<uint32_t> words) {
328   unsigned wordIndex = 0;
329   if (wordIndex >= words.size()) {
330     return emitError(unknownLoc,
331                      "missing Execution Model specification in OpEntryPoint");
332   }
333   auto execModel = opBuilder.getI32IntegerAttr(words[wordIndex++]);
334   if (wordIndex >= words.size()) {
335     return emitError(unknownLoc, "missing <id> in OpEntryPoint");
336   }
337   // Get the function <id>
338   auto fnID = words[wordIndex++];
339   // Get the function name
340   auto fnName = decodeStringLiteral(words, wordIndex);
341   // Verify that the function <id> matches the fnName
342   auto parsedFunc = getFunction(fnID);
343   if (!parsedFunc) {
344     return emitError(unknownLoc, "no function matching <id> ") << fnID;
345   }
346   if (parsedFunc.getName() != fnName) {
347     return emitError(unknownLoc, "function name mismatch between OpEntryPoint "
348                                  "and OpFunction with <id> ")
349            << fnID << ": " << fnName << " vs. " << parsedFunc.getName();
350   }
351   SmallVector<Attribute, 4> interface;
352   while (wordIndex < words.size()) {
353     auto arg = getGlobalVariable(words[wordIndex]);
354     if (!arg) {
355       return emitError(unknownLoc, "undefined result <id> ")
356              << words[wordIndex] << " while decoding OpEntryPoint";
357     }
358     interface.push_back(opBuilder.getSymbolRefAttr(arg.getOperation()));
359     wordIndex++;
360   }
361   opBuilder.create<spirv::EntryPointOp>(unknownLoc, execModel,
362                                         opBuilder.getSymbolRefAttr(fnName),
363                                         opBuilder.getArrayAttr(interface));
364   return success();
365 }
366 
367 template <>
368 LogicalResult
369 Deserializer::processOp<spirv::ExecutionModeOp>(ArrayRef<uint32_t> words) {
370   unsigned wordIndex = 0;
371   if (wordIndex >= words.size()) {
372     return emitError(unknownLoc,
373                      "missing function result <id> in OpExecutionMode");
374   }
375   // Get the function <id> to get the name of the function
376   auto fnID = words[wordIndex++];
377   auto fn = getFunction(fnID);
378   if (!fn) {
379     return emitError(unknownLoc, "no function matching <id> ") << fnID;
380   }
381   // Get the Execution mode
382   if (wordIndex >= words.size()) {
383     return emitError(unknownLoc, "missing Execution Mode in OpExecutionMode");
384   }
385   auto execMode = opBuilder.getI32IntegerAttr(words[wordIndex++]);
386 
387   // Get the values
388   SmallVector<Attribute, 4> attrListElems;
389   while (wordIndex < words.size()) {
390     attrListElems.push_back(opBuilder.getI32IntegerAttr(words[wordIndex++]));
391   }
392   auto values = opBuilder.getArrayAttr(attrListElems);
393   opBuilder.create<spirv::ExecutionModeOp>(
394       unknownLoc, opBuilder.getSymbolRefAttr(fn.getName()), execMode, values);
395   return success();
396 }
397 
398 template <>
399 LogicalResult
400 Deserializer::processOp<spirv::ControlBarrierOp>(ArrayRef<uint32_t> operands) {
401   if (operands.size() != 3) {
402     return emitError(
403         unknownLoc,
404         "OpControlBarrier must have execution scope <id>, memory scope <id> "
405         "and memory semantics <id>");
406   }
407 
408   SmallVector<IntegerAttr, 3> argAttrs;
409   for (auto operand : operands) {
410     auto argAttr = getConstantInt(operand);
411     if (!argAttr) {
412       return emitError(unknownLoc,
413                        "expected 32-bit integer constant from <id> ")
414              << operand << " for OpControlBarrier";
415     }
416     argAttrs.push_back(argAttr);
417   }
418 
419   opBuilder.create<spirv::ControlBarrierOp>(unknownLoc, argAttrs[0],
420                                             argAttrs[1], argAttrs[2]);
421   return success();
422 }
423 
424 template <>
425 LogicalResult
426 Deserializer::processOp<spirv::FunctionCallOp>(ArrayRef<uint32_t> operands) {
427   if (operands.size() < 3) {
428     return emitError(unknownLoc,
429                      "OpFunctionCall must have at least 3 operands");
430   }
431 
432   Type resultType = getType(operands[0]);
433   if (!resultType) {
434     return emitError(unknownLoc, "undefined result type from <id> ")
435            << operands[0];
436   }
437 
438   // Use null type to mean no result type.
439   if (isVoidType(resultType))
440     resultType = nullptr;
441 
442   auto resultID = operands[1];
443   auto functionID = operands[2];
444 
445   auto functionName = getFunctionSymbol(functionID);
446 
447   SmallVector<Value, 4> arguments;
448   for (auto operand : llvm::drop_begin(operands, 3)) {
449     auto value = getValue(operand);
450     if (!value) {
451       return emitError(unknownLoc, "unknown <id> ")
452              << operand << " used by OpFunctionCall";
453     }
454     arguments.push_back(value);
455   }
456 
457   auto opFunctionCall = opBuilder.create<spirv::FunctionCallOp>(
458       unknownLoc, resultType, opBuilder.getSymbolRefAttr(functionName),
459       arguments);
460 
461   if (resultType)
462     valueMap[resultID] = opFunctionCall.getResult(0);
463   return success();
464 }
465 
466 template <>
467 LogicalResult
468 Deserializer::processOp<spirv::MemoryBarrierOp>(ArrayRef<uint32_t> operands) {
469   if (operands.size() != 2) {
470     return emitError(unknownLoc, "OpMemoryBarrier must have memory scope <id> "
471                                  "and memory semantics <id>");
472   }
473 
474   SmallVector<IntegerAttr, 2> argAttrs;
475   for (auto operand : operands) {
476     auto argAttr = getConstantInt(operand);
477     if (!argAttr) {
478       return emitError(unknownLoc,
479                        "expected 32-bit integer constant from <id> ")
480              << operand << " for OpMemoryBarrier";
481     }
482     argAttrs.push_back(argAttr);
483   }
484 
485   opBuilder.create<spirv::MemoryBarrierOp>(unknownLoc, argAttrs[0],
486                                            argAttrs[1]);
487   return success();
488 }
489 
490 template <>
491 LogicalResult
492 Deserializer::processOp<spirv::CopyMemoryOp>(ArrayRef<uint32_t> words) {
493   SmallVector<Type, 1> resultTypes;
494   size_t wordIndex = 0;
495   SmallVector<Value, 4> operands;
496   SmallVector<NamedAttribute, 4> attributes;
497 
498   if (wordIndex < words.size()) {
499     auto arg = getValue(words[wordIndex]);
500 
501     if (!arg) {
502       return emitError(unknownLoc, "unknown result <id> : ")
503              << words[wordIndex];
504     }
505 
506     operands.push_back(arg);
507     wordIndex++;
508   }
509 
510   if (wordIndex < words.size()) {
511     auto arg = getValue(words[wordIndex]);
512 
513     if (!arg) {
514       return emitError(unknownLoc, "unknown result <id> : ")
515              << words[wordIndex];
516     }
517 
518     operands.push_back(arg);
519     wordIndex++;
520   }
521 
522   bool isAlignedAttr = false;
523 
524   if (wordIndex < words.size()) {
525     auto attrValue = words[wordIndex++];
526     attributes.push_back(opBuilder.getNamedAttr(
527         "memory_access", opBuilder.getI32IntegerAttr(attrValue)));
528     isAlignedAttr = (attrValue == 2);
529   }
530 
531   if (isAlignedAttr && wordIndex < words.size()) {
532     attributes.push_back(opBuilder.getNamedAttr(
533         "alignment", opBuilder.getI32IntegerAttr(words[wordIndex++])));
534   }
535 
536   if (wordIndex < words.size()) {
537     attributes.push_back(opBuilder.getNamedAttr(
538         "source_memory_access",
539         opBuilder.getI32IntegerAttr(words[wordIndex++])));
540   }
541 
542   if (wordIndex < words.size()) {
543     attributes.push_back(opBuilder.getNamedAttr(
544         "source_alignment", opBuilder.getI32IntegerAttr(words[wordIndex++])));
545   }
546 
547   if (wordIndex != words.size()) {
548     return emitError(unknownLoc,
549                      "found more operands than expected when deserializing "
550                      "spirv::CopyMemoryOp, only ")
551            << wordIndex << " of " << words.size() << " processed";
552   }
553 
554   Location loc = createFileLineColLoc(opBuilder);
555   opBuilder.create<spirv::CopyMemoryOp>(loc, resultTypes, operands, attributes);
556 
557   return success();
558 }
559 
560 // Pull in auto-generated Deserializer::dispatchToAutogenDeserialization() and
561 // various Deserializer::processOp<...>() specializations.
562 #define GET_DESERIALIZATION_FNS
563 #include "mlir/Dialect/SPIRV/IR/SPIRVSerialization.inc"
564 
565 } // namespace spirv
566 } // namespace mlir
567