Add text format specification for Linking.md #258
Conversation
Linking.md
Outdated
| | `weak` | sets `WASM_SYM_BINDING_WEAK` symbol flag | | ||
| | `static` | sets `WASM_SYM_BINDING_LOCAL` symbol flag | | ||
| | `hidden` | sets `WASM_SYM_VISIBILITY_HIDDEN` symbol flag | | ||
| | `retain` | sets `WASM_SYM_NO_STRIP` symbol flag | |
There was a problem hiding this comment.
If we think retain is a better terminology then we should probably propose renaming WASM_SYM_NO_STRIP rather than diverging.
There was a problem hiding this comment.
Yeah, that's sound. I just thought that those names are from LLVM's source, so that rename should be done in sync with LLVM
|
For comparison I wonder if you could post a simple |
I can do that for WAT, but since I don't really know the structure of |
|
On second thought, I can just use |
|
@sbc100 My "hello world" examples turned out to be more than a full screen of code when using |
Can you just include it here as quoted text? Along with the equivalent wat for comparison? |
Agreed, Im mostly curious to see the two side by side here in the comments for comparison/discussion. |
|
Oh, sure, then, for the source file test.cpp, when compiled with (Unfortunately, github forbids me from posting |
Oh nice, the wat format looks much more readable than I expected it to be. |
|
One thing I wanted to mention here is that there is a limitation in the text format, that code section relocations that do not make sense for instruction operands may not be expressed in the text format. So for example |
|
Also the same issue exists for labels, which can only point between instructions in the code segment, or into the data area of a data segment in the data section |
Yes it seems perfectly reasonable for an object file validator to declare such relocations as invalid based on the instructions they are part of. However, the linker itself (wasm-ld) will blindly accept such things, and likely produce invalid output as a result too. The linker explictly does not parse the code section but instead blindly applies relocation. The same goes for relocation that don't point to a correct spot in the instruction stream, e.g. a relocation could in theory point at the |
|
Would you be fine with me adding into the doc that such relocations are invalid for the purposes of validation, then? |
Sure that makes sense to me. Relocation that don't point to a valid spot in the instruction stream are certainly invalid. It might be worth also noting that wasm-ld does not do validation of the code section though, so bad inputs can result in bad outputs.
Sounds reasonable yes, we could always expand the list, but for now those are the only sections that are copied by the linker from input files into the output file, so they are the only section for which relocations make sense. I think for GC types we maybe want to one day include the type section somehow, but we are long way from that. |
|
Added the validation rules, please take a look |
Linking.md
Outdated
| | ------------ | -------------- | ------------------------------------------- | | ||
| | section | `varuint32` | the index of the target section | | ||
|
|
||
| Section symbols may only reference the CODE section, the DATA section, or custom sections. |
There was a problem hiding this comment.
Hm.. I'm not sure about this actually.
When you asked about documenting a limitation on sections I thought you were referring to the fact that relocations can only apply to certain section types.
"Which sections can have relocations within them" is a different concept to "which sections can be referred to by WASM_SYMBOL_TYPE_SECTION symbols".
I believe that WASM_SYMBOL_TYPE_SECTION symbols are only used by debug info, but my memory is a little foggy here.
Looking at the code it actually looks like this symbols might only be valid for custom sections: https://github.com/llvm/llvm-project/blob/38372df53fd7f6c8bd8c46bf720b676e12f481d9/lld/wasm/InputFiles.cpp#L697-L705.
Which would make sense if these only used in debug info since all debug info is stored in custom sections.
There was a problem hiding this comment.
I don't believe it can work like that, though, since R_WASM_SECTION_OFFSET_I32 relocations reference a section symbol, and for that to work as DWARF code addresses, the symbol that relocation references would have to reference the CODE section, while the relocation itself would have to target a place in the debug section.
There was a problem hiding this comment.
No, actually, that can absolutely work if WASM_*_OFFSET_* relocations actually resolve to offsets form the file start, like DWARF actually expects. I do think the current spec is not very clear on this and someone from LLVM should take a look at what actually happens there and adjust https://github.com/WebAssembly/tool-conventions/blob/main/Linking.md#processing-relocations accordingly.
I think a simple hello world in C should be enough since that will include a function relocation for |
|
One aspect I'd like to see as well is relocations within a data section too, but compiling hello world with |
Relocations in data sections already have an example in https://github.com/feedab1e/tool-conventions/blob/main/Linking.md#data-relocations, perhaps you meant something else? |
|
As for disassembling a "hello world" compiled with |
As per current primary symbol rules, the relocation annotation for |
I see so there would still be a reloc entry in the binary but not the the test format. When relocation entries are implicit like this how does the binary writer know to produce them? Would there be special flag to the wat2wasm program that says something like |
Yes, that flag already exists in |
|
The caveat here is that currently |
Do you think this a good design (its something I just threw together back in the day)? I wonder if "explicit relocs everywhere" might not be better? Otherwise won't all the tools that do text to binary conversion will need some kind of extra flag to see if implicit relocs are enabled or not? Or can we magically enable implicit relocs whenever we see any kind linking annotation in the wat file? Could there exist a wat file with zero explict annotations? How would the tooling know to create a linking section or not in that case? |
Well, it does make the code prettier, and it does allow to link against all existing WAT modules with no source changes, I see that as a benefit.
Well, if we really do want that, I suppose we could dispatch based on whether the features section is present. But that wouldn't be reliable in any case, since tooling that isn't relocation-aware would skip unknown annotations and silently yield a simple module instead of an object file. |
I may not fully be following the context here, but my hope is that |
So, @sbc100 is basically asking if it would be possible at all to assemble a file form WAT without emitting relocation metadata. For disassembly it'd be easy, since it's always obvious if a file is an object file based on the presence of the relevant custom sections. But for assembly with current syntax, any valid text module can also be an object file now. |
I suppose we could make a rule such as "If at least one explicit linking annotation exists in the wat file then the whole file is assumed to be relocatable, and implicit relocations will be injected/generated in all possible locations" Should we go with "at least on explicit annotation" or should we maybe have some kind of top level annotation that expresses "this is a relocatable object file"? |
|
Something like |
|
Looking at prior art, if I am to run |
I think they would appear in the binary if and only if they appear in the source (wat). The idea of creating implicit annotations (i.e. annotation that don't exist in the wat file at all) is the tricky thing here. I'm not sure its good idea to that route. |
Well, I can make a description for target-features, require that to be present for the binary to be relocatable |
|
Personally I would advocate for |
I would assume, then, that a reasonable implementation of that would always generate the sections internally, but then strip them during output, unless either a flag or either |
|
My assumption is that the presence of |
|
By "default" do you mean "if no linking annotations are present in the file" (i.e. not creating an object file) or do you mean just silently not generating a relocation there? |
|
I guess my actual question is how would you diagnose the following: (module
(func (param) (result))
(func (@sym) (param) (result)))It is either
Option 1 would require either restarting the parse, or remembering all of the declaration locations, and then issuing an error for every one that had no annotations. |
How about we require |
|
Could handling func-with- |
Sure, but how would you implement those diagnostics? The parser state is gone by the time you do object file validation, as well as source locations for the declarations. |
That would work, too. Actually, then, I think it would be better to have an annotation describing all WAT features that are enabled for the module. (module (@wat-features linking code-metadata dwarf))For object file linking specifically, another option is to say something like (module (@target-features +overlong-leb -multimemory))to trigger object file generation, since those make sense only for linking, AFAIK |
3 participants
This PR proposes a vendor-neutral syntax for describing relocation information in WAT.
Unlike the syntax described in WebAssembly/wabt#2649, this proposal is intended to express everything that the binary format can, including whatever the current proposed implementation in WABT does not support. Of note here is the fact that
@symannotations can appear multiple times per declaration, the inclusion of COMDATs, segment infos, and the inclusion of labels and addends.