1//===- Wasm.h - Wasm object file format -------------------------*- C++ -*-===//
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 manifest constants for the wasm object file format.
10// See: https://github.com/WebAssembly/design/blob/main/BinaryEncoding.md
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_BINARYFORMAT_WASM_H
15#define LLVM_BINARYFORMAT_WASM_H
16
17#include "llvm/ADT/ArrayRef.h"
18#include "llvm/ADT/SmallVector.h"
19#include "llvm/ADT/StringRef.h"
20#include <optional>
21
22namespace llvm {
23namespace wasm {
24
25// Object file magic string.
26const char WasmMagic[] = {'\0', 'a', 's', 'm'};
27// Wasm binary format version
28const uint32_t WasmVersion = 0x1;
29// Wasm linking metadata version
30const uint32_t WasmMetadataVersion = 0x2;
31// Wasm uses a 64k page size
32const uint32_t WasmPageSize = 65536;
33
34enum : unsigned {
35 WASM_SEC_CUSTOM = 0, // Custom / User-defined section
36 WASM_SEC_TYPE = 1, // Function signature declarations
37 WASM_SEC_IMPORT = 2, // Import declarations
38 WASM_SEC_FUNCTION = 3, // Function declarations
39 WASM_SEC_TABLE = 4, // Indirect function table and other tables
40 WASM_SEC_MEMORY = 5, // Memory attributes
41 WASM_SEC_GLOBAL = 6, // Global declarations
42 WASM_SEC_EXPORT = 7, // Exports
43 WASM_SEC_START = 8, // Start function declaration
44 WASM_SEC_ELEM = 9, // Elements section
45 WASM_SEC_CODE = 10, // Function bodies (code)
46 WASM_SEC_DATA = 11, // Data segments
47 WASM_SEC_DATACOUNT = 12, // Data segment count
48 WASM_SEC_TAG = 13, // Tag declarations
49 WASM_SEC_LAST_KNOWN = WASM_SEC_TAG,
50};
51
52// Type immediate encodings used in various contexts.
53enum : unsigned {
54 WASM_TYPE_I32 = 0x7F,
55 WASM_TYPE_I64 = 0x7E,
56 WASM_TYPE_F32 = 0x7D,
57 WASM_TYPE_F64 = 0x7C,
58 WASM_TYPE_V128 = 0x7B,
59 WASM_TYPE_NULLFUNCREF = 0x73,
60 WASM_TYPE_NULLEXTERNREF = 0x72,
61 WASM_TYPE_NULLREF = 0x71,
62 WASM_TYPE_FUNCREF = 0x70,
63 WASM_TYPE_EXTERNREF = 0x6F,
64 WASM_TYPE_ANYREF = 0x6E,
65 WASM_TYPE_EQREF = 0x6D,
66 WASM_TYPE_I31REF = 0x6C,
67 WASM_TYPE_STRUCTREF = 0x6B,
68 WASM_TYPE_ARRAYREF = 0x6A,
69 WASM_TYPE_EXNREF = 0x69,
70 WASM_TYPE_NONNULLABLE = 0x64,
71 WASM_TYPE_NULLABLE = 0x63,
72 WASM_TYPE_FUNC = 0x60,
73 WASM_TYPE_ARRAY = 0x5E,
74 WASM_TYPE_STRUCT = 0x5F,
75 WASM_TYPE_SUB = 0x50,
76 WASM_TYPE_SUB_FINAL = 0x4F,
77 WASM_TYPE_REC = 0x4E,
78 WASM_TYPE_NORESULT = 0x40, // for blocks with no result values
79};
80
81// Kinds of externals (for imports and exports).
82enum : unsigned {
83 WASM_EXTERNAL_FUNCTION = 0x0,
84 WASM_EXTERNAL_TABLE = 0x1,
85 WASM_EXTERNAL_MEMORY = 0x2,
86 WASM_EXTERNAL_GLOBAL = 0x3,
87 WASM_EXTERNAL_TAG = 0x4,
88};
89
90// Opcodes used in initializer expressions.
91enum : unsigned {
92 WASM_OPCODE_END = 0x0b,
93 WASM_OPCODE_CALL = 0x10,
94 WASM_OPCODE_LOCAL_GET = 0x20,
95 WASM_OPCODE_LOCAL_SET = 0x21,
96 WASM_OPCODE_LOCAL_TEE = 0x22,
97 WASM_OPCODE_GLOBAL_GET = 0x23,
98 WASM_OPCODE_GLOBAL_SET = 0x24,
99 WASM_OPCODE_I32_STORE = 0x36,
100 WASM_OPCODE_I64_STORE = 0x37,
101 WASM_OPCODE_I32_CONST = 0x41,
102 WASM_OPCODE_I64_CONST = 0x42,
103 WASM_OPCODE_F32_CONST = 0x43,
104 WASM_OPCODE_F64_CONST = 0x44,
105 WASM_OPCODE_I32_ADD = 0x6a,
106 WASM_OPCODE_I32_SUB = 0x6b,
107 WASM_OPCODE_I32_MUL = 0x6c,
108 WASM_OPCODE_I64_ADD = 0x7c,
109 WASM_OPCODE_I64_SUB = 0x7d,
110 WASM_OPCODE_I64_MUL = 0x7e,
111 WASM_OPCODE_REF_NULL = 0xd0,
112 WASM_OPCODE_REF_FUNC = 0xd2,
113 WASM_OPCODE_GC_PREFIX = 0xfb,
114};
115
116// Opcodes in the GC-prefixed space (0xfb)
117enum : unsigned {
118 WASM_OPCODE_STRUCT_NEW = 0x00,
119 WASM_OPCODE_STRUCT_NEW_DEFAULT = 0x01,
120 WASM_OPCODE_ARRAY_NEW = 0x06,
121 WASM_OPCODE_ARRAY_NEW_DEFAULT = 0x07,
122 WASM_OPCODE_ARRAY_NEW_FIXED = 0x08,
123 WASM_OPCODE_REF_I31 = 0x1c,
124 // any.convert_extern and extern.convert_any don't seem to be supported by
125 // Binaryen.
126};
127
128// Opcodes used in synthetic functions.
129enum : unsigned {
130 WASM_OPCODE_BLOCK = 0x02,
131 WASM_OPCODE_BR = 0x0c,
132 WASM_OPCODE_BR_TABLE = 0x0e,
133 WASM_OPCODE_RETURN = 0x0f,
134 WASM_OPCODE_DROP = 0x1a,
135 WASM_OPCODE_MISC_PREFIX = 0xfc,
136 WASM_OPCODE_MEMORY_INIT = 0x08,
137 WASM_OPCODE_MEMORY_FILL = 0x0b,
138 WASM_OPCODE_DATA_DROP = 0x09,
139 WASM_OPCODE_ATOMICS_PREFIX = 0xfe,
140 WASM_OPCODE_ATOMIC_NOTIFY = 0x00,
141 WASM_OPCODE_I32_ATOMIC_WAIT = 0x01,
142 WASM_OPCODE_I32_ATOMIC_STORE = 0x17,
143 WASM_OPCODE_I32_RMW_CMPXCHG = 0x48,
144};
145
146enum : unsigned {
147 WASM_LIMITS_FLAG_NONE = 0x0,
148 WASM_LIMITS_FLAG_HAS_MAX = 0x1,
149 WASM_LIMITS_FLAG_IS_SHARED = 0x2,
150 WASM_LIMITS_FLAG_IS_64 = 0x4,
151};
152
153enum : unsigned {
154 WASM_DATA_SEGMENT_IS_PASSIVE = 0x01,
155 WASM_DATA_SEGMENT_HAS_MEMINDEX = 0x02,
156};
157
158enum : unsigned {
159 WASM_ELEM_SEGMENT_IS_PASSIVE = 0x01,
160 WASM_ELEM_SEGMENT_IS_DECLARATIVE = 0x02, // if passive == 1
161 WASM_ELEM_SEGMENT_HAS_TABLE_NUMBER = 0x02, // if passive == 0
162 WASM_ELEM_SEGMENT_HAS_INIT_EXPRS = 0x04,
163};
164const unsigned WASM_ELEM_SEGMENT_MASK_HAS_ELEM_KIND = 0x3;
165
166// Feature policy prefixes used in the custom "target_features" section
167enum : uint8_t {
168 WASM_FEATURE_PREFIX_USED = '+',
169 WASM_FEATURE_PREFIX_REQUIRED = '=',
170 WASM_FEATURE_PREFIX_DISALLOWED = '-',
171};
172
173// Kind codes used in the custom "name" section
174enum : unsigned {
175 WASM_NAMES_MODULE = 0,
176 WASM_NAMES_FUNCTION = 1,
177 WASM_NAMES_LOCAL = 2,
178 WASM_NAMES_GLOBAL = 7,
179 WASM_NAMES_DATA_SEGMENT = 9,
180};
181
182// Kind codes used in the custom "linking" section
183enum : unsigned {
184 WASM_SEGMENT_INFO = 0x5,
185 WASM_INIT_FUNCS = 0x6,
186 WASM_COMDAT_INFO = 0x7,
187 WASM_SYMBOL_TABLE = 0x8,
188};
189
190// Kind codes used in the custom "dylink" section
191enum : unsigned {
192 WASM_DYLINK_MEM_INFO = 0x1,
193 WASM_DYLINK_NEEDED = 0x2,
194 WASM_DYLINK_EXPORT_INFO = 0x3,
195 WASM_DYLINK_IMPORT_INFO = 0x4,
196};
197
198// Kind codes used in the custom "linking" section in the WASM_COMDAT_INFO
199enum : unsigned {
200 WASM_COMDAT_DATA = 0x0,
201 WASM_COMDAT_FUNCTION = 0x1,
202 // GLOBAL, TAG, and TABLE are in here but LLVM doesn't use them yet.
203 WASM_COMDAT_SECTION = 0x5,
204};
205
206// Kind codes used in the custom "linking" section in the WASM_SYMBOL_TABLE
207enum WasmSymbolType : unsigned {
208 WASM_SYMBOL_TYPE_FUNCTION = 0x0,
209 WASM_SYMBOL_TYPE_DATA = 0x1,
210 WASM_SYMBOL_TYPE_GLOBAL = 0x2,
211 WASM_SYMBOL_TYPE_SECTION = 0x3,
212 WASM_SYMBOL_TYPE_TAG = 0x4,
213 WASM_SYMBOL_TYPE_TABLE = 0x5,
214};
215
216enum WasmSegmentFlag : unsigned {
217 WASM_SEG_FLAG_STRINGS = 0x1,
218 WASM_SEG_FLAG_TLS = 0x2,
219 WASM_SEG_FLAG_RETAIN = 0x4,
220};
221
222// Kinds of tag attributes.
223enum WasmTagAttribute : uint8_t {
224 WASM_TAG_ATTRIBUTE_EXCEPTION = 0x0,
225};
226
227const unsigned WASM_SYMBOL_BINDING_MASK = 0x3;
228const unsigned WASM_SYMBOL_VISIBILITY_MASK = 0xc;
229
230const unsigned WASM_SYMBOL_BINDING_GLOBAL = 0x0;
231const unsigned WASM_SYMBOL_BINDING_WEAK = 0x1;
232const unsigned WASM_SYMBOL_BINDING_LOCAL = 0x2;
233const unsigned WASM_SYMBOL_VISIBILITY_DEFAULT = 0x0;
234const unsigned WASM_SYMBOL_VISIBILITY_HIDDEN = 0x4;
235const unsigned WASM_SYMBOL_UNDEFINED = 0x10;
236const unsigned WASM_SYMBOL_EXPORTED = 0x20;
237const unsigned WASM_SYMBOL_EXPLICIT_NAME = 0x40;
238const unsigned WASM_SYMBOL_NO_STRIP = 0x80;
239const unsigned WASM_SYMBOL_TLS = 0x100;
240const unsigned WASM_SYMBOL_ABSOLUTE = 0x200;
241
242#define WASM_RELOC(name, value) name = value,
243
244enum : unsigned {
245#include "WasmRelocs.def"
246};
247
248#undef WASM_RELOC
249
250struct WasmObjectHeader {
251 StringRef Magic;
252 uint32_t Version;
253};
254
255// Subset of types that a value can have
256enum class ValType {
257 I32 = WASM_TYPE_I32,
258 I64 = WASM_TYPE_I64,
259 F32 = WASM_TYPE_F32,
260 F64 = WASM_TYPE_F64,
261 V128 = WASM_TYPE_V128,
262 FUNCREF = WASM_TYPE_FUNCREF,
263 EXTERNREF = WASM_TYPE_EXTERNREF,
264 // Unmodeled value types include ref types with heap types other than
265 // func or extern, and type-specialized funcrefs
266 OTHERREF = 0xff,
267};
268
269struct WasmDylinkImportInfo {
270 StringRef Module;
271 StringRef Field;
272 uint32_t Flags;
273};
274
275struct WasmDylinkExportInfo {
276 StringRef Name;
277 uint32_t Flags;
278};
279
280struct WasmDylinkInfo {
281 uint32_t MemorySize; // Memory size in bytes
282 uint32_t MemoryAlignment; // P2 alignment of memory
283 uint32_t TableSize; // Table size in elements
284 uint32_t TableAlignment; // P2 alignment of table
285 std::vector<StringRef> Needed; // Shared library dependencies
286 std::vector<WasmDylinkImportInfo> ImportInfo;
287 std::vector<WasmDylinkExportInfo> ExportInfo;
288};
289
290struct WasmProducerInfo {
291 std::vector<std::pair<std::string, std::string>> Languages;
292 std::vector<std::pair<std::string, std::string>> Tools;
293 std::vector<std::pair<std::string, std::string>> SDKs;
294};
295
296struct WasmFeatureEntry {
297 uint8_t Prefix;
298 std::string Name;
299};
300
301struct WasmExport {
302 StringRef Name;
303 uint8_t Kind;
304 uint32_t Index;
305};
306
307struct WasmLimits {
308 uint8_t Flags;
309 uint64_t Minimum;
310 uint64_t Maximum;
311};
312
313struct WasmTableType {
314 ValType ElemType;
315 WasmLimits Limits;
316};
317
318struct WasmTable {
319 uint32_t Index;
320 WasmTableType Type;
321 StringRef SymbolName; // from the "linking" section
322};
323
324struct WasmInitExprMVP {
325 uint8_t Opcode;
326 union {
327 int32_t Int32;
328 int64_t Int64;
329 uint32_t Float32;
330 uint64_t Float64;
331 uint32_t Global;
332 } Value;
333};
334
335// Extended-const init exprs and exprs with GC types are not explicitly
336// modeled, but the raw body of the expr is attached.
337struct WasmInitExpr {
338 uint8_t Extended; // Set to non-zero if extended const is used (i.e. more than
339 // one instruction)
340 WasmInitExprMVP Inst;
341 ArrayRef<uint8_t> Body;
342};
343
344struct WasmGlobalType {
345 uint8_t Type; // TODO: make this a ValType?
346 bool Mutable;
347};
348
349struct WasmGlobal {
350 uint32_t Index;
351 WasmGlobalType Type;
352 WasmInitExpr InitExpr;
353 StringRef SymbolName; // from the "linking" section
354 uint32_t Offset; // Offset of the definition in the binary's Global section
355 uint32_t Size; // Size of the definition in the binary's Global section
356};
357
358struct WasmTag {
359 uint32_t Index;
360 uint32_t SigIndex;
361 StringRef SymbolName; // from the "linking" section
362};
363
364struct WasmImport {
365 StringRef Module;
366 StringRef Field;
367 uint8_t Kind;
368 union {
369 uint32_t SigIndex;
370 WasmGlobalType Global;
371 WasmTableType Table;
372 WasmLimits Memory;
373 };
374};
375
376struct WasmLocalDecl {
377 uint8_t Type;
378 uint32_t Count;
379};
380
381struct WasmFunction {
382 uint32_t Index;
383 uint32_t SigIndex;
384 std::vector<WasmLocalDecl> Locals;
385 ArrayRef<uint8_t> Body;
386 uint32_t CodeSectionOffset;
387 uint32_t Size;
388 uint32_t CodeOffset; // start of Locals and Body
389 std::optional<StringRef> ExportName; // from the "export" section
390 StringRef SymbolName; // from the "linking" section
391 StringRef DebugName; // from the "name" section
392 uint32_t Comdat; // from the "comdat info" section
393};
394
395struct WasmDataSegment {
396 uint32_t InitFlags;
397 // Present if InitFlags & WASM_DATA_SEGMENT_HAS_MEMINDEX.
398 uint32_t MemoryIndex;
399 // Present if InitFlags & WASM_DATA_SEGMENT_IS_PASSIVE == 0.
400 WasmInitExpr Offset;
401
402 ArrayRef<uint8_t> Content;
403 StringRef Name; // from the "segment info" section
404 uint32_t Alignment;
405 uint32_t LinkingFlags;
406 uint32_t Comdat; // from the "comdat info" section
407};
408
409// Represents a Wasm element segment, with some limitations compared the spec:
410// 1) Does not model passive or declarative segments (Segment will end up with
411// an Offset field of i32.const 0)
412// 2) Does not model init exprs (Segment will get an empty Functions list)
413// 2) Does not model types other than basic funcref/externref (see ValType)
414struct WasmElemSegment {
415 uint32_t Flags;
416 uint32_t TableNumber;
417 ValType ElemKind;
418 WasmInitExpr Offset;
419 std::vector<uint32_t> Functions;
420};
421
422// Represents the location of a Wasm data symbol within a WasmDataSegment, as
423// the index of the segment, and the offset and size within the segment.
424struct WasmDataReference {
425 uint32_t Segment;
426 uint64_t Offset;
427 uint64_t Size;
428};
429
430struct WasmRelocation {
431 uint8_t Type; // The type of the relocation.
432 uint32_t Index; // Index into either symbol or type index space.
433 uint64_t Offset; // Offset from the start of the section.
434 int64_t Addend; // A value to add to the symbol.
435};
436
437struct WasmInitFunc {
438 uint32_t Priority;
439 uint32_t Symbol;
440};
441
442struct WasmSymbolInfo {
443 StringRef Name;
444 uint8_t Kind;
445 uint32_t Flags;
446 // For undefined symbols the module of the import
447 std::optional<StringRef> ImportModule;
448 // For undefined symbols the name of the import
449 std::optional<StringRef> ImportName;
450 // For symbols to be exported from the final module
451 std::optional<StringRef> ExportName;
452 union {
453 // For function, table, or global symbols, the index in function, table, or
454 // global index space.
455 uint32_t ElementIndex;
456 // For a data symbols, the address of the data relative to segment.
457 WasmDataReference DataRef;
458 };
459};
460
461enum class NameType {
462 FUNCTION,
463 GLOBAL,
464 DATA_SEGMENT,
465};
466
467struct WasmDebugName {
468 NameType Type;
469 uint32_t Index;
470 StringRef Name;
471};
472
473// Info from the linking metadata section of a wasm object file.
474struct WasmLinkingData {
475 uint32_t Version;
476 std::vector<WasmInitFunc> InitFunctions;
477 std::vector<StringRef> Comdats;
478 // The linking section also contains a symbol table. This info (represented
479 // in a WasmSymbolInfo struct) is stored inside the WasmSymbol object instead
480 // of in this structure; this allows vectors of WasmSymbols and
481 // WasmLinkingDatas to be reallocated.
482};
483
484struct WasmSignature {
485 SmallVector<ValType, 1> Returns;
486 SmallVector<ValType, 4> Params;
487 // LLVM can parse types other than functions encoded in the type section,
488 // but does not actually model them. Instead a placeholder signature is
489 // created in the Object's signature list.
490 enum { Function, Tag, Placeholder } Kind = Function;
491 // Support empty and tombstone instances, needed by DenseMap.
492 enum { Plain, Empty, Tombstone } State = Plain;
493
494 WasmSignature(SmallVector<ValType, 1> &&InReturns,
495 SmallVector<ValType, 4> &&InParams)
496 : Returns(InReturns), Params(InParams) {}
497 WasmSignature() = default;
498};
499
500// Useful comparison operators
501inline bool operator==(const WasmSignature &LHS, const WasmSignature &RHS) {
502 return LHS.State == RHS.State && LHS.Returns == RHS.Returns &&
503 LHS.Params == RHS.Params;
504}
505
506inline bool operator!=(const WasmSignature &LHS, const WasmSignature &RHS) {
507 return !(LHS == RHS);
508}
509
510inline bool operator==(const WasmGlobalType &LHS, const WasmGlobalType &RHS) {
511 return LHS.Type == RHS.Type && LHS.Mutable == RHS.Mutable;
512}
513
514inline bool operator!=(const WasmGlobalType &LHS, const WasmGlobalType &RHS) {
515 return !(LHS == RHS);
516}
517
518inline bool operator==(const WasmLimits &LHS, const WasmLimits &RHS) {
519 return LHS.Flags == RHS.Flags && LHS.Minimum == RHS.Minimum &&
520 (LHS.Flags & WASM_LIMITS_FLAG_HAS_MAX ? LHS.Maximum == RHS.Maximum
521 : true);
522}
523
524inline bool operator==(const WasmTableType &LHS, const WasmTableType &RHS) {
525 return LHS.ElemType == RHS.ElemType && LHS.Limits == RHS.Limits;
526}
527
528llvm::StringRef toString(WasmSymbolType type);
529llvm::StringRef relocTypetoString(uint32_t type);
530llvm::StringRef sectionTypeToString(uint32_t type);
531bool relocTypeHasAddend(uint32_t type);
532
533} // end namespace wasm
534} // end namespace llvm
535
536#endif
537

source code of llvm/include/llvm/BinaryFormat/Wasm.h