Path to phase 4

[tlively]

Here are the phase 4 entry requirements:

• Two or more Web VMs have implemented the feature and pass the test suite (where applicable).
  • V8
  • JSC
• At least one toolchain has implemented the feature (where applicable).
  • Cheerp
• The spec document has been fully updated in the forked repo.
• The reference interpreter has been fully updated in the forked repo and passes the test suite.
• The Community Group has reached consensus in support of the feature and consensus that its specification is complete.

On the face of things, it seems that the only thing left to do would be to vote this to phase 4. Indeed, the last time this was discussed in a CG meeting, it seemed like the only blocker was getting the annotations proposal to phase 4 because this on depends on that. Is that correct? Are there any other issues to resolve before this goes to phase 4?

[yuri91]

Thanks for the recap!

Indeed the only blocker is the annotations proposal.

Although, connected to the annotation proposal there is the issue of where to put the spec. It is complete, and it currently resides in the Appendix ,as does the spec for the annotations proposal.

@rossberg pointed out that this is might not be the proper place for them, considering that we are going to add a few more.

If the annotation proposal will move the spec text somewhere else, this proposal will do the same.

[rossberg]

Yeah, the spec shouldn't become a dumping ground for arbitrary custom section specifications. But if we allow in some it will be difficult to reject others. So, we should always separate concrete custom sections/annotations from the core specification document, except perhaps for the most basic/universal ones like the name section (though I wouldn't ming moving that out as well).

(A clarification: the main part of the annotations proposal is a generic extension to the text format, which resides in the main body of the spec. That will of course stay there. We are only talking about concrete custom formats.)

For the exception proposal, I already created a separate document to specify the legacy proposal behaviour, linked off the main page, see here. I suggest we take a similar format for each custom section.

[yuri91]

@rossberg do you suggest that we have a separate document/link for each custom section (all linked in the main page) or that we put them in a common document?

Actually there is a third option: group them by format. Currently there is the "code metadata" format, for instruction-level annotations/sections, and in the compilation hints proposal they are thinking of making a "function metadata" format for function-level ones (although the former could also be used)

[rossberg]

I like your third option! I would not throw everything into a single document, for the same reasons as above.

[yuri91]

@rossberg I gave option 3 a try, following what you did for the exception handling legacy document.

You can see a first draft here: https://webassembly.github.io/branch-hinting/

Since the idea is to have a document that describes all the code metadata sections, I incorporated the general description from https://github.com/WebAssembly/tool-conventions/blob/main/CodeMetadata.md , and defined branch hints based on that.

I am having trouble to come up with a formal description of the abstract structure (hence some TODOs in that section), so any suggestion here is appreciated.

The hyperlinks that point to the core spec are broken, but they are also for the legacy exceptions document. I think it should be relatively easy to fix in the mathdef.py script, but for now I didn't bother.

I should also probably add some language that specifically states that the document is based on the core spec and its definitions.

Before adding any improvement I would appreciate feedback on the general structure.

[rossberg]

Great, I'll have a look! But I'm about to leave for a couple of days, so that might not happen before Tuesday.

[rossberg]

Sorry for the delay. The structure looks good to me! As one remark, I perhaps would avoid speaking of metadata "type", to avoid confusion with actual types. Call it something like "kind" or "format" instead.

I have a couple of typographical comments, but I can do them on the concrete source code later on.

[yuri91]

Thanks!

I agree about the overloaded term "type". I like "format" as an alternative.

Since the structure looks good, I will try to fix the broken links to the main spec, and maybe get the core spec math macros from the original folder instead of duplicating the files.