WebAssembly / WebAssembly/spec

Inconsistencies across multiple pages of instruction lists

Open
#2,020 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
WebAssembly
Stars
3.5k
Forks
539
Avg merge
2d 1h
Merged PRs (30d)
13

Description

Hello, I'm beginning to study Wasm as a hobby. I think I've found some editorial bugs.

As a first step in learning, I wanted to know what kind of instructions Wasm has, so I searched and found wasm-ops. That chart was a great help, but I noticed it was a bit outdated, so I next tried to create a new chart.

Since I was at it, I thought I'd automate the table creation and started writing a script. But now, as a beginner, I'm a bit confused.

When I generated a table from the instruction list, I realized multiple name inconsistencies within the specification pages themselves.

I found such inconsistencies on (at least) three pages. I believe that each pages provide a comprehensive list of Wasm instructions.

  1. Index of Instructions^1
  2. Instructions in Binary Format section^2
  3. Instructions in Structure section^3

The following are examples of contradiction. I'm not sure which one is correct, but could you fix the inconsistencies?

  • ^1 contains end (0x0B), but ^3 does not, and ^2 does not refer to it in instr :: = definition
  • ^1 and ^3 contain call_ref (0x14), but ^2 does not
  • ^1 contains instructions that end with {name}_{numtype}_{sx} (like i32.trunc_f32_u), but others contain {name}_{sx}_{numtype} (i32.trunc_u_f32) with the same {name}
  • ^2 says 0xBB is f32.promote_f64 but others say it's f64.promote_f32
  • [Update] ^2 and Text Format^6 categorizes struct.*/array.* as "Reference Instructions," as the same as ref.*, but ^3 categorizes them as a separate "Aggregate Instructions"
    • In addition, Validation^4 categorizes them as "Aggregate Reference Instructions" (another different name)

However, I don't believe the above is complete. For example, there seem to be at least three other pages titled "Instructions,"^4^6 but I haven't investigated those yet.

I would appreciate it if they could be corrected.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the six linked WebAssembly specification instruction pages: Index of Instructions, Binary Format, Structure, Validation, Execution, and Text Format. Check the reported instruction names, opcode 0xBB, and category labels against one another and determine the authoritative forms. Done means the instruction lists and classifications are consistent across the referenced pages.

Written by the indexing model from the issue text.

Assessment

Tech stack
wasm
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.