Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 38 ยท Modules, Memory and Tables

Module Structure and Sections

Learn every section of a WebAssembly binary module, their order, index spaces, the start function and custom sections, with a runnable section dumper.

You already built modules from four sections. A full module can have up to twelve kinds of section, and each one describes a different part of the program. This lesson is the map of the whole format. Once you know it, any .wasm file you meet, from a tiny helper to a compiled game engine, becomes readable.

The sections

Sections appear in a fixed order (except custom sections, which can go anywhere). Each starts with its numeric id and a byte size, which lets a tool skip sections it does not care about.

Id Name Contents
0 Custom Name plus arbitrary bytes: debug names, source maps, producer info
1 Type Function signatures
2 Import Functions, tables, memories and globals provided by the host
3 Function Type index of each function defined in this module
4 Table Tables (arrays of references, usually function references)
5 Memory Linear memories with size limits
6 Global Global variables with initial values
7 Export Names the host can use
8 Start One function that runs automatically at instantiation
9 Element Initial contents of tables
12 Data count Number of data segments (needed for bulk memory)
10 Code Function bodies
11 Data Initial contents of memory

Notice that the Data Count section (id 12) sits between Element and Code even though its number is higher. Order, not number, is what matters, and the order exists so an engine can compile function bodies in parallel as soon as it has seen all the declarations. That is also why all code comes near the end.

flowchart LR
    H["Header"] --> T["Type 1"] --> I["Import 2"] --> F["Function 3"] --> TB["Table 4"] --> M["Memory 5"] --> G["Global 6"] --> E["Export 7"] --> S["Start 8"] --> EL["Element 9"] --> C["Code 10"] --> D["Data 11"]

Index spaces

A module refers to things by number. There is a separate numbering, called an index space, for types, functions, tables, memories and globals. In each space the imports come first, then the things the module defines itself. If a module imports two functions and defines three, the local functions are numbered 2, 3 and 4. This is why call 0 in the last lesson called the import.

Types and function bodies are separate: the Function section lists one type index per local function, and the Code section lists the bodies in the same order.

Limits

Memories and tables declare limits: a minimum size, and optionally a maximum. In binary a limit is a flag byte (0x00 for minimum only, 0x01 for minimum and maximum) followed by the numbers. Memory sizes are counted in pages of 64 KiB (65,536 bytes). A module with min 1 starts with 64 KiB.

A section dumper

Here is a small tool that reads a module and prints its sections. It reuses the byte builder and makes a module that uses almost every section: an imported function that doubles as the start function (it runs while the instance is being created), a table, a memory, a global, an exported function and a data segment that stores the text "hi" in memory.

Node.js Dump the sections of a module

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

You can see the start function print its message before any of your own calls. A start function is the way a module can run set-up code with no explicit call, but it runs before the exports object is returned, so it cannot call your exports. Many toolchains use an exported _initialize function instead, which gives the host control over when set-up happens.

The data segment copied the two bytes h and i into memory address 0 during instantiation. The next lessons explore memory and data in depth.

Custom sections

A custom section (id 0) is ignored by the engine. It can appear anywhere, any number of times, and it carries a name plus any bytes. Tools use them for:

  • name: human-readable names of functions and locals, so stack traces say parse_header instead of func[17].
  • producers: which compiler and version produced the file.
  • sourceMappingURL and DWARF sections: debugging information, covered in the debugging chapter.
  • target_features and dylink.0: used by linkers and loaders.

You can read them from JavaScript with WebAssembly.Module.customSections(module, 'name'). Stripping custom sections (for example with wasm-strip) shrinks a release file without changing behavior.

Order and size are enforced

Break the order and the module is rejected, even though every individual section is fine. This is a good habit test for hand-written modules.

Node.js Sections in the wrong order

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A module imports 2 functions and defines 3. What index does its first locally defined function have?

    Imports come first in each index space, so the two imports take 0 and 1 and the local functions are 2, 3 and 4.
  2. 2. How big is one WebAssembly memory page?

    Memory limits and sizes are always counted in 64 KiB pages.
  3. 3. What is true about custom sections?

    Engines skip custom sections. Tools use them for names, debug info and metadata.
  4. 4. When does the start function run?

    The start function is run automatically while the module is instantiated.

Summary

  • A module is a header plus ordered sections: type, import, function, table, memory, global, export, start, element, code, data.
  • Custom sections may appear anywhere and carry names, debug info and tool metadata.
  • Index spaces number imports first, then local definitions.
  • Limits are minimum and optional maximum; memory pages are 64 KiB.
  • The start function runs automatically during instantiation.
  • Engines reject modules whose sections are out of order or whose counts disagree.

Next: Linear Memory