1//===- Serializer.h - MLIR SPIR-V Serializer ------------------------------===//
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 declares the MLIR SPIR-V module to SPIR-V binary serializer.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef MLIR_LIB_TARGET_SPIRV_SERIALIZATION_SERIALIZER_H
14#define MLIR_LIB_TARGET_SPIRV_SERIALIZATION_SERIALIZER_H
15
16#include "mlir/Dialect/SPIRV/IR/SPIRVOps.h"
17#include "mlir/IR/Builders.h"
18#include "mlir/Target/SPIRV/SPIRVExtInstSets.h"
19#include "mlir/Target/SPIRV/Serialization.h"
20#include "llvm/ADT/SetVector.h"
21#include "llvm/ADT/SmallVector.h"
22#include "llvm/Support/raw_ostream.h"
23
24namespace mlir {
25namespace spirv {
26
27void encodeInstructionInto(SmallVectorImpl<uint32_t> &binary, spirv::Opcode op,
28 ArrayRef<uint32_t> operands);
29
30/// A SPIR-V module serializer.
31///
32/// A SPIR-V binary module is a single linear stream of instructions; each
33/// instruction is composed of 32-bit words with the layout:
34///
35/// | <word-count>|<opcode> | <operand> | <operand> | ... |
36/// | <------ word -------> | <-- word --> | <-- word --> | ... |
37///
38/// For the first word, the 16 high-order bits are the word count of the
39/// instruction, the 16 low-order bits are the opcode enumerant. The
40/// instructions then belong to different sections, which must be laid out in
41/// the particular order as specified in "2.4 Logical Layout of a Module" of
42/// the SPIR-V spec.
43class Serializer {
44public:
45 /// Creates a serializer for the given SPIR-V `module`.
46 explicit Serializer(spirv::ModuleOp module,
47 const SerializationOptions &options);
48
49 /// Serializes the remembered SPIR-V module.
50 LogicalResult serialize();
51
52 /// Collects the final SPIR-V `binary`.
53 void collect(SmallVectorImpl<uint32_t> &binary);
54
55#ifndef NDEBUG
56 /// (For debugging) prints each value and its corresponding result <id>.
57 void printValueIDMap(raw_ostream &os);
58#endif
59
60private:
61 // Note that there are two main categories of methods in this class:
62 // * process*() methods are meant to fully serialize a SPIR-V module entity
63 // (header, type, op, etc.). They update internal vectors containing
64 // different binary sections. They are not meant to be called except the
65 // top-level serialization loop.
66 // * prepare*() methods are meant to be helpers that prepare for serializing
67 // certain entity. They may or may not update internal vectors containing
68 // different binary sections. They are meant to be called among themselves
69 // or by other process*() methods for subtasks.
70
71 //===--------------------------------------------------------------------===//
72 // <id>
73 //===--------------------------------------------------------------------===//
74
75 // Note that it is illegal to use id <0> in SPIR-V binary module. Various
76 // methods in this class, if using SPIR-V word (uint32_t) as interface,
77 // check or return id <0> to indicate error in processing.
78
79 /// Consumes the next unused <id>. This method will never return 0.
80 uint32_t getNextID() { return nextID++; }
81
82 //===--------------------------------------------------------------------===//
83 // Module structure
84 //===--------------------------------------------------------------------===//
85
86 uint32_t getSpecConstID(StringRef constName) const {
87 return specConstIDMap.lookup(Key: constName);
88 }
89
90 uint32_t getVariableID(StringRef varName) const {
91 return globalVarIDMap.lookup(Key: varName);
92 }
93
94 uint32_t getFunctionID(StringRef fnName) const {
95 return funcIDMap.lookup(Key: fnName);
96 }
97
98 /// Gets the <id> for the function with the given name. Assigns the next
99 /// available <id> if the function haven't been deserialized.
100 uint32_t getOrCreateFunctionID(StringRef fnName);
101
102 void processCapability();
103
104 void processDebugInfo();
105
106 LogicalResult processExtension();
107
108 /// Encodes `op` + `operands` into `binary`, splitting via the
109 /// SPV_INTEL_long_composites continuation opcode when the total word count
110 /// would exceed kMaxWordCount. `op` must be a splittable composite/struct
111 /// opcode (see getContinuationOpcode). The capability and extension are
112 /// emitted lazily on first split.
113 void encodeInstructionWithContinuationInto(SmallVectorImpl<uint32_t> &binary,
114 spirv::Opcode op,
115 ArrayRef<uint32_t> operands);
116
117 void addLongCompositesCapability();
118
119 void processMemoryModel();
120
121 LogicalResult processConstantOp(spirv::ConstantOp op);
122
123 LogicalResult processCompositeConstructOp(spirv::CompositeConstructOp op);
124
125 LogicalResult processConstantCompositeReplicateOp(
126 spirv::EXTConstantCompositeReplicateOp op);
127
128 LogicalResult processSpecConstantOp(spirv::SpecConstantOp op);
129
130 LogicalResult
131 processSpecConstantCompositeOp(spirv::SpecConstantCompositeOp op);
132
133 LogicalResult processSpecConstantCompositeReplicateOp(
134 spirv::EXTSpecConstantCompositeReplicateOp op);
135
136 LogicalResult
137 processSpecConstantOperationOp(spirv::SpecConstantOperationOp op);
138
139 LogicalResult processGraphConstantARMOp(spirv::GraphConstantARMOp op);
140
141 /// SPIR-V dialect supports OpUndef using spirv.UndefOp that produces a SSA
142 /// value to use with other operations. The SPIR-V spec recommends that
143 /// OpUndef be generated at module level. The serialization generates an
144 /// OpUndef for each type needed at module level.
145 LogicalResult processUndefOp(spirv::UndefOp op);
146
147 /// Emit OpName for the given `resultID`.
148 LogicalResult processName(uint32_t resultID, StringRef name);
149
150 /// Processes a SPIR-V function op.
151 LogicalResult processFuncOp(spirv::FuncOp op);
152 LogicalResult processFuncParameter(spirv::FuncOp op);
153
154 /// Processes a SPIR-V GraphARM op.
155 LogicalResult processGraphARMOp(spirv::GraphARMOp op);
156
157 /// Processes a SPIR-V GraphEntryPointARM op.
158 LogicalResult processGraphEntryPointARMOp(spirv::GraphEntryPointARMOp op);
159
160 /// Processes a SPIR-V GraphOutputsARMOp op.
161 LogicalResult processGraphOutputsARMOp(spirv::GraphOutputsARMOp op);
162
163 LogicalResult processVariableOp(spirv::VariableOp op);
164
165 /// Process a SPIR-V GlobalVariableOp
166 LogicalResult processGlobalVariableOp(spirv::GlobalVariableOp varOp);
167
168 /// Process attributes that translate to decorations on the result <id>
169 LogicalResult processDecorationAttr(Location loc, uint32_t resultID,
170 Decoration decoration, Attribute attr);
171 LogicalResult processDecoration(Location loc, uint32_t resultID,
172 NamedAttribute attr);
173
174 template <typename DType>
175 LogicalResult processTypeDecoration(Location loc, DType type,
176 uint32_t resultId) {
177 return emitError(loc, message: "unhandled decoration for type:") << type;
178 }
179
180 /// Process member decoration
181 LogicalResult processMemberDecoration(
182 uint32_t structID,
183 const spirv::StructType::MemberDecorationInfo &memberDecorationInfo);
184
185 //===--------------------------------------------------------------------===//
186 // Types
187 //===--------------------------------------------------------------------===//
188
189 uint32_t getTypeID(Type type) const { return typeIDMap.lookup(Val: type); }
190
191 Type getVoidType() { return mlirBuilder.getNoneType(); }
192
193 bool isVoidType(Type type) const { return isa<NoneType>(Val: type); }
194
195 /// Returns true if the given type is a pointer type to a struct in some
196 /// interface storage class.
197 bool isInterfaceStructPtrType(Type type) const;
198
199 /// Main dispatch method for serializing a type. The result <id> of the
200 /// serialized type will be returned as `typeID`.
201 LogicalResult processType(Location loc, Type type, uint32_t &typeID);
202 LogicalResult processTypeImpl(Location loc, Type type, uint32_t &typeID,
203 SetVector<StringRef> &serializationCtx);
204
205 /// Method for preparing basic SPIR-V type serialization. Returns the type's
206 /// opcode and operands for the instruction via `typeEnum` and `operands`.
207 LogicalResult prepareBasicType(Location loc, Type type, uint32_t resultID,
208 spirv::Opcode &typeEnum,
209 SmallVectorImpl<uint32_t> &operands,
210 bool &deferSerialization,
211 SetVector<StringRef> &serializationCtx);
212
213 LogicalResult prepareFunctionType(Location loc, FunctionType type,
214 spirv::Opcode &typeEnum,
215 SmallVectorImpl<uint32_t> &operands);
216
217 LogicalResult prepareGraphType(Location loc, GraphType type,
218 spirv::Opcode &typeEnum,
219 SmallVectorImpl<uint32_t> &operands);
220
221 //===--------------------------------------------------------------------===//
222 // Constant
223 //===--------------------------------------------------------------------===//
224
225 uint32_t getConstantID(Attribute value) const {
226 return constIDMap.lookup(Val: value);
227 }
228
229 uint32_t getConstantCompositeReplicateID(
230 std::pair<Attribute, Type> valueTypePair) const {
231 return constCompositeReplicateIDMap.lookup(Val: valueTypePair);
232 }
233
234 /// Main dispatch method for processing a constant with the given `constType`
235 /// and `valueAttr`. `constType` is needed here because we can interpret the
236 /// `valueAttr` as a different type than the type of `valueAttr` itself; for
237 /// example, ArrayAttr, whose type is NoneType, is used for spirv::ArrayType
238 /// constants.
239 uint32_t prepareConstant(Location loc, Type constType, Attribute valueAttr);
240
241 /// Prepares array attribute serialization. This method emits corresponding
242 /// OpConstant* and returns the result <id> associated with it. Returns 0 if
243 /// failed.
244 uint32_t prepareArrayConstant(Location loc, Type constType, ArrayAttr attr);
245
246 /// Prepares bool/int/float DenseElementsAttr serialization. This method
247 /// iterates the DenseElementsAttr to construct the constant array, and
248 /// returns the result <id> associated with it. Returns 0 if failed. Note
249 /// that the size of `index` must match the rank.
250 /// TODO: Consider to enhance splat elements cases. For splat cases,
251 /// we don't need to loop over all elements, especially when the splat value
252 /// is zero. We can use OpConstantNull when the value is zero.
253 uint32_t prepareDenseElementsConstant(Location loc, Type constType,
254 DenseElementsAttr valueAttr, int dim,
255 MutableArrayRef<uint64_t> index);
256
257 /// Prepares scalar attribute serialization. This method emits corresponding
258 /// OpConstant* and returns the result <id> associated with it. Returns 0 if
259 /// the attribute is not for a scalar bool/integer/float value. If `isSpec` is
260 /// true, then the constant will be serialized as a specialization constant.
261 uint32_t prepareConstantScalar(Location loc, Attribute valueAttr,
262 bool isSpec = false);
263
264 uint32_t prepareConstantBool(Location loc, BoolAttr boolAttr,
265 bool isSpec = false);
266
267 uint32_t prepareConstantInt(Location loc, IntegerAttr intAttr,
268 bool isSpec = false);
269
270 uint32_t getGraphConstantARMId(Attribute value) const {
271 return graphConstIDMap.lookup(Val: value);
272 }
273
274 uint32_t prepareGraphConstantId(Location loc, Type graphConstType,
275 IntegerAttr intAttr);
276
277 uint32_t prepareConstantFp(Location loc, FloatAttr floatAttr,
278 bool isSpec = false);
279
280 /// Prepares `spirv.EXTConstantCompositeReplicateOp` serialization. This
281 /// method emits OpConstantCompositeReplicateEXT and returns the result <id>
282 /// associated with it.
283 uint32_t prepareConstantCompositeReplicate(Location loc, Type resultType,
284 Attribute valueAttr);
285
286 //===--------------------------------------------------------------------===//
287 // Control flow
288 //===--------------------------------------------------------------------===//
289
290 /// Returns the result <id> for the given block.
291 uint32_t getBlockID(Block *block) const { return blockIDMap.lookup(Val: block); }
292
293 /// Returns the result <id> for the given block. If no <id> has been assigned,
294 /// assigns the next available <id>
295 uint32_t getOrCreateBlockID(Block *block);
296
297#ifndef NDEBUG
298 /// (For debugging) prints the block with its result <id>.
299 void printBlock(Block *block, raw_ostream &os);
300#endif
301
302 /// Processes the given `block` and emits SPIR-V instructions for all ops
303 /// inside. Does not emit OpLabel for this block if `omitLabel` is true.
304 /// `emitMerge` is a callback that will be invoked before handling the
305 /// terminator op to inject the Op*Merge instruction if this is a SPIR-V
306 /// selection/loop header block.
307 LogicalResult processBlock(Block *block, bool omitLabel = false,
308 function_ref<LogicalResult()> emitMerge = nullptr);
309
310 /// Emits OpPhi instructions for the given block if it has block arguments.
311 LogicalResult emitPhiForBlockArguments(Block *block);
312
313 LogicalResult processSelectionOp(spirv::SelectionOp selectionOp);
314
315 LogicalResult processLoopOp(spirv::LoopOp loopOp);
316
317 LogicalResult processBranchConditionalOp(spirv::BranchConditionalOp);
318
319 LogicalResult processBranchOp(spirv::BranchOp branchOp);
320
321 LogicalResult processSwitchOp(spirv::SwitchOp switchOp);
322
323 //===--------------------------------------------------------------------===//
324 // Operations
325 //===--------------------------------------------------------------------===//
326
327 LogicalResult encodeExtensionInstruction(Operation *op,
328 StringRef extensionSetName,
329 uint32_t opcode,
330 ArrayRef<uint32_t> operands);
331
332 LogicalResult encodeExtensionInstruction(Operation *op,
333 StringRef extensionSetName,
334 uint32_t opcode,
335 ArrayRef<uint32_t> operands,
336 SmallVectorImpl<uint32_t> &binary);
337
338 uint32_t encodeDebugStringInst(StringRef str);
339
340 LogicalResult encodeDebugInfoGraphInst(spirv::GraphARMOp op,
341 uint32_t &debugGraphID);
342
343 LogicalResult encodeDebugInfoOperationInst(uint32_t debugGraphID,
344 const SetVector<Operation *> &ops);
345
346 LogicalResult encodeDebugInfoTensorInst(Value tensor);
347
348 uint32_t getValueID(Value val) const { return valueIDMap.lookup(Val: val); }
349
350 LogicalResult processAddressOfOp(spirv::AddressOfOp addressOfOp);
351
352 LogicalResult processReferenceOfOp(spirv::ReferenceOfOp referenceOfOp);
353
354 /// Main dispatch method for serializing an operation.
355 LogicalResult processOperation(Operation *op);
356
357 /// Serializes an operation `op` as core instruction with `opcode` if
358 /// `extInstSet` is empty. Otherwise serializes it as an extended instruction
359 /// with `opcode` from `extInstSet`.
360 /// This method is a generic one for dispatching any SPIR-V ops that has no
361 /// variadic operands and attributes in TableGen definitions.
362 LogicalResult processOpWithoutGrammarAttr(Operation *op, StringRef extInstSet,
363 uint32_t opcode);
364
365 /// Dispatches to the serialization function for an operation in SPIR-V
366 /// dialect that is a mirror of an instruction in the SPIR-V spec. This is
367 /// auto-generated from ODS. Dispatch is handled for all operations in SPIR-V
368 /// dialect that have hasOpcode == 1.
369 LogicalResult dispatchToAutogenSerialization(Operation *op);
370
371 /// Serializes an operation in the SPIR-V dialect that is a mirror of an
372 /// instruction in the SPIR-V spec. This is auto generated if hasOpcode == 1
373 /// and autogenSerialization == 1 in ODS.
374 template <typename OpTy>
375 LogicalResult processOp(OpTy op) {
376 return op.emitError("unsupported op serialization");
377 }
378
379 //===--------------------------------------------------------------------===//
380 // Utilities
381 //===--------------------------------------------------------------------===//
382
383 /// Updates tosaOpsMap after ensuring that the op is inside a graph.
384 void updateTosaOpsMap(Operation *op);
385
386 /// Emits an OpDecorate instruction to decorate the given `target` with the
387 /// given `decoration`.
388 LogicalResult emitDecoration(uint32_t target, spirv::Decoration decoration,
389 ArrayRef<uint32_t> params = {});
390
391 /// Emits an OpDecorateId instruction to decorate the given `target` with the
392 /// given `decoration` whose extra operands are SPIR-V <id>s.
393 LogicalResult emitDecorationId(uint32_t target, spirv::Decoration decoration,
394 ArrayRef<uint32_t> operandIds);
395
396 /// Emits an OpLine instruction with the given `loc` location information into
397 /// the given `binary` vector.
398 LogicalResult emitDebugLine(SmallVectorImpl<uint32_t> &binary, Location loc);
399
400private:
401 /// The SPIR-V module to be serialized.
402 spirv::ModuleOp module;
403
404 /// An MLIR builder for getting MLIR constructs.
405 mlir::Builder mlirBuilder;
406
407 /// Serialization options.
408 SerializationOptions options;
409
410 /// A flag which indicates if the last processed instruction was a merge
411 /// instruction.
412 /// According to SPIR-V spec: "If a branch merge instruction is used, the last
413 /// OpLine in the block must be before its merge instruction".
414 bool lastProcessedWasMergeInst = false;
415
416 /// The <id> of the OpString instruction, which specifies a file name, for
417 /// use by other debug instructions.
418 uint32_t fileID = 0;
419
420 /// Map from graph debug info string payloads to their OpString <id>s.
421 llvm::StringMap<uint32_t> debugStringIDMap;
422
423 /// The next available result <id>.
424 uint32_t nextID = 1;
425
426 bool longCompositesEmitted = false;
427
428 // The following are for different SPIR-V instruction sections. They follow
429 // the logical layout of a SPIR-V module.
430
431 SmallVector<uint32_t, 4> capabilities;
432 SmallVector<uint32_t, 0> extensions;
433 SmallVector<uint32_t, 0> extendedSets;
434 SmallVector<uint32_t, 3> memoryModel;
435 SmallVector<uint32_t, 0> entryPoints;
436 SmallVector<uint32_t, 4> executionModes;
437 SmallVector<uint32_t, 0> debug;
438 SmallVector<uint32_t, 0> names;
439 SmallVector<uint32_t, 0> decorations;
440 SmallVector<uint32_t, 0> typesGlobalValues;
441 SmallVector<uint32_t, 0> functions;
442 SmallVector<uint32_t, 0> graphs;
443 SmallVector<uint32_t, 0> graphsDebugInfo;
444
445 /// Recursive struct references are serialized as OpTypePointer instructions
446 /// to the recursive struct type. However, the OpTypePointer instruction
447 /// cannot be emitted before the recursive struct's OpTypeStruct.
448 /// RecursiveStructPointerInfo stores the data needed to emit such
449 /// OpTypePointer instructions after forward references to such types.
450 struct RecursiveStructPointerInfo {
451 uint32_t pointerTypeID;
452 spirv::StorageClass storageClass;
453 };
454
455 // Maps spirv::StructType to its recursive reference member info.
456 DenseMap<Type, SmallVector<RecursiveStructPointerInfo, 0>>
457 recursiveStructInfos;
458
459 /// `functionHeader` contains all the instructions that must be in the first
460 /// block in the function or graph, and `functionBody` contains the rest.
461 /// After processing FuncOp/GraphARMOp, the encoded instructions of a function
462 /// or graph are appended to `functions` or `graphs` respectively. Examples of
463 /// instructions in `functionHeader` in order:
464 ///
465 /// For a FuncOp:
466 /// OpFunction ...
467 /// OpFunctionParameter ...
468 /// OpFunctionParameter ...
469 /// OpLabel ...
470 /// OpVariable ...
471 /// OpVariable ...
472 ///
473 /// For a GraphARMOp
474 /// OpGraphARM ...
475 /// OpGraphInputARM ...
476 SmallVector<uint32_t, 0> functionHeader;
477 SmallVector<uint32_t, 0> functionBody;
478
479 /// Map from type used in SPIR-V module to their <id>s.
480 DenseMap<Type, uint32_t> typeIDMap;
481
482 /// Map from constant values to their <id>s.
483 DenseMap<Attribute, uint32_t> constIDMap;
484
485 /// Map from a replicated composite constant's value and type to their <id>s.
486 DenseMap<std::pair<Attribute, Type>, uint32_t> constCompositeReplicateIDMap;
487
488 /// Map from specialization constant names to their <id>s.
489 llvm::StringMap<uint32_t> specConstIDMap;
490
491 /// Map from graph constant ID value to their <id>s.
492 DenseMap<Attribute, uint32_t> graphConstIDMap;
493
494 /// Map from GlobalVariableOps name to <id>s.
495 llvm::StringMap<uint32_t> globalVarIDMap;
496
497 /// Map from FuncOps name to <id>s.
498 llvm::StringMap<uint32_t> funcIDMap;
499
500 /// Map from blocks to their <id>s.
501 DenseMap<Block *, uint32_t> blockIDMap;
502
503 /// Map from the Type to the <id> that represents undef value of that type.
504 DenseMap<Type, uint32_t> undefValIDMap;
505
506 /// Map from results of normal operations to their <id>s.
507 DenseMap<Value, uint32_t> valueIDMap;
508
509 /// Map from extended instruction set name to <id>s.
510 llvm::StringMap<uint32_t> extendedInstSetIDMap;
511
512 /// Map of graph <id> to map of locations in that graph to set of tosa ops in
513 /// that location
514 DenseMap<uint32_t, DenseMap<Location, SetVector<Operation *>>> tosaOpsMap;
515
516 /// Map from values used in OpPhi instructions to their offset in the
517 /// `functions` section.
518 ///
519 /// When processing a block with arguments, we need to emit OpPhi
520 /// instructions to record the predecessor block <id>s and the values they
521 /// send to the block in question. But it's not guaranteed all values are
522 /// visited and thus assigned result <id>s. So we need this list to capture
523 /// the offsets into `functions` where a value is used so that we can fix it
524 /// up later after processing all the blocks in a function.
525 ///
526 /// More concretely, say if we are visiting the following blocks:
527 ///
528 /// ```mlir
529 /// ^phi(%arg0: i32):
530 /// ...
531 /// ^parent1:
532 /// ...
533 /// spirv.Branch ^phi(%val0: i32)
534 /// ^parent2:
535 /// ...
536 /// spirv.Branch ^phi(%val1: i32)
537 /// ```
538 ///
539 /// When we are serializing the `^phi` block, we need to emit at the beginning
540 /// of the block OpPhi instructions which has the following parameters:
541 ///
542 /// OpPhi id-for-i32 id-for-%arg0 id-for-%val0 id-for-^parent1
543 /// id-for-%val1 id-for-^parent2
544 ///
545 /// But we don't know the <id> for %val0 and %val1 yet. One way is to visit
546 /// all the blocks twice and use the first visit to assign an <id> to each
547 /// value. But it's paying the overheads just for OpPhi emission. Instead,
548 /// we still visit the blocks once for emission. When we emit the OpPhi
549 /// instructions, we use 0 as a placeholder for the <id>s for %val0 and %val1.
550 /// At the same time, we record their offsets in the emitted binary (which is
551 /// placed inside `functions`) here. And then after emitting all blocks, we
552 /// replace the dummy <id> 0 with the real result <id> by overwriting
553 /// `functions[offset]`.
554 DenseMap<Value, SmallVector<size_t, 1>> deferredPhiValues;
555};
556} // namespace spirv
557} // namespace mlir
558
559#endif // MLIR_LIB_TARGET_SPIRV_SERIALIZATION_SERIALIZER_H
560