Custom annotations on functions

[kripken]

I understand how custom annotations work on instructions, but I am confused about functions, and I see multiple options in the ecosystem. The tool-conventions repo has this example, annotation before the name:

;; option A
(func (@metadata.code.hotness "\01") $test (type 0).

The annotations repo has this example, annotation after the name:

;; option B
(func $lambda (@name "λ") (param $x (@name "α βγ δ") i32) (result i32) (local.get $x))

The first one is for the function, surely, given the name matches the function, and also the param has its own annotation later...? But that seems ambiguous in a function with no params or results: (func $foo (@something) (nop)) - is that annotation on the nop, or the function..?

The binaryen parser expects annotations before the entire function (same as for instructions):

;; option C
(@metadata.code.inline "\12") (func $annotated-func
  (local $x i32)

  (@metadata.code.branch_hint "\01")
  (if .. ;; annotated instruction in function

I can't figure out which of A, B, C is correct from the spec text. I may be misreading it, though, or not reading the right place? (In particular, I don't see details about how annotations work on instructions, like branch hinting or compilation hints use annotations - is that documented elsewhere?)

[fgmccabe]

This: https://github.com/WebAssembly/annotations/blob/main/document/core/appendix/custom.rst#:~:text=If%20both%20an%20identifier%20and%20a%20name%20annotation%20are%20given%2C%20the%20annotation%20is%20expected%20after%20the%20identifier

suggests that the annotation should go after the name being annotated. That is also consistent with how Java annotations work.

[kripken]

@fgmccabe Hmm, is that part not specifically for Name annotations? It is in the "Name Annotations" subsection.

(Though maybe it suggests a general rule?)

[fgmccabe]

Yes, I was inferring a general rule from one example :)

[rossberg]

As far as the core spec (minus the Appendix) is concerned, annotations are just syntax without any prescribed meaning and can appear anywhere — just like custom sections. It's up to the custom spec to say anything more specific. That said, it would be good to share the same conventions.

[kripken]

@rossberg

I see, thanks. Still, while the meaning of annotations is left to feature proposals, should the core spec not say something about what annotations attach to?

Concretely, consider the ambiguity problem mentioned above, that is,

(func $func
  (@metadata.code.something) ;; is this on the function or the nop?
  (nop)

Imagine an IDE that shows annotations when you hover over things. Even if the IDE does not understand an annotation's meaning, being able to show it is useful, but it needs to at least know what entity to attach the annotation to. If some IDEs show it on the function and others on the nop, that seems unfortunate.

[tlively]

@kripken, the notion of attaching to anything at all is part of the semantics of the annotation, so cannot be described in general for all annotations. The best we can do is document non-normative best practices for the design of future annotations.

[rossberg]

What @tlively said. There is no presumed connection to the AST at all. All the core spec does is allowing the (lexical) syntax, in the same spirit that custom sections are allowed with no further assumptions. A tool or IDE is no more expected to be able to do anything useful with a random annotation that it doesn't understand than with a custom section that it doesn't understand.

[kripken]

Interesting, I guess my perspective is different than you two... Intuitively, to me it seems reasonable to say something about the syntax of annotations (which includes relative position), but nothing about their semantics.

A tool or IDE is no more expected to be able to do anything useful with a random annotation that it doesn't understand than with a custom section that it doesn't understand.

Yes, but it can preserve that custom section: it can keep it there, unmodified, and in the same relative position to others. E.g. appending another section at the end would be ok (maybe even inserting in the middle, if later sections don't use absolute offsets...)

Right now, tools have a decent chance of preserving unknown custom sections in the binary. It would be nice if the text format had something like that too. (But maybe the place for it isn't in the core spec?)

[rossberg]

@kripken, tools that modify a module cannot preserve unknown custom sections either, since those generally would need updating as well, consider e.g. code positions in code metadata sections. That corresponds to knowing what a textual annotation is attached to.

A generic mechanism for AST annotations (in both text and binary) could of course be defined on top of what we have now. But I doubt it would be useful. Even with that, tools wouldn't really be able to preserve unknown sections/annotations, because they still cannot know whether or how they'd need to update or amend the contents of such annotations. For example, imagine a custom mechanism that encodes auxiliary type information for instructions in some way. Preserving unknown custom stuff in a non-broken manner seems fundamentally impossible to me.

[kripken]

@rossberg

tools that modify a module cannot preserve unknown custom sections either, since those generally would need updating as well, consider e.g. code positions in code metadata sections. That corresponds to knowing what a textual annotation is attached to.

Yes, if the tool modifies code. But if the tool adds analysis without altering code, it can work.

For example, a tool that does a complex whole-program analysis to find unlikely code paths can insert a branch hinting section into the wasm. All other custom sections can be preserved without changes in the binary. This is a good property I think.

Now, imagine a similar tool working on the text format rather than the binary. If the syntax of text annotations is defined, it can insert new annotations without breaking existing ones.

For example, imagine a custom mechanism that encodes auxiliary type information for instructions in some way. Preserving unknown custom stuff in a non-broken manner seems fundamentally impossible to me.

Yes, definitely, this cannot work in general, if the wasm changes.

[rossberg]

@kripken, why would the same not work with the text format? As long as you are just inserting additional annotations, and you know where those have to go, isn't everything fine?