You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is version 0 of the WebAssembly module Webcil wrapper.
5
+
This described version 0.0, and 1.0 of the Webcil payload format.
6
+
This describes version 0 and 1 of the WebAssembly module Webcil wrapper.
7
7
8
8
## Motivation
9
9
@@ -74,6 +74,75 @@ module without instantiating it to properly parse the ECMA-335 metadata in the W
74
74
75
75
(**Note**: the wrapper may be versioned independently of the payload.)
76
76
77
+
#### WebAssembly module Webcil wrapper format version 1
78
+
Version 1 of the WebAssembly module Webcil wrapper adds an additional capability and requirements.
79
+
If data segment 0 is at least 8 bytes in size, and the second 4 bytes has a non-zero value when interpreted as a 4-byte
80
+
little-endian unsigned 32-bit integer, then data segment 0 encodes two little-endian
81
+
u32 values: `payloadSize` (first 4 bytes) and `tableSize` (second 4 bytes). In this case,
82
+
`tableSize` shall be the number of table entries required for the WebAssembly
83
+
module to be loaded, and the module shall import a table, as well as `stackPointer`, `tableBase`, and
84
+
`imageBase` globals. There shall also be a `fillWebcilTable` function which will initialize the table
85
+
with appropriate values. The `getWebcilPayload` API shall be enhanced to fill in the `TableBase` field
86
+
of the `WebcilHeader`.
87
+
88
+
The memory of the WebcilPayload must also be allocated with 16 byte alignment.
89
+
90
+
```wat
91
+
(module
92
+
(data "\0f\00\00\00\01\00\00\00") ;; data segment 0: two little-endian u32 values (payloadSize, tableSize). This specifies a Webcil payload of size 15 bytes with 1 required table entry
93
+
(data "webcil Payload\cc") ;; data segment 1: Webcil payload
;; Set the table base, if the amount of data to write is large enough
112
+
local.get 1
113
+
i32.const 32 ;; the amount of bytes required so that the write below does not overflow the size specified
114
+
i32.ge_s
115
+
if
116
+
local.get 0
117
+
global.get 2 ;; get the tableBase from the global assigned during instantiate
118
+
i32.store offset=28
119
+
end
120
+
)
121
+
(func (export "fillWebcilTable") (result)
122
+
global.get 2 ;; function pointers to fill in start at tableBase
123
+
i32.const 0
124
+
i32.const 1 ;; There is 1 element in elem segment 0
125
+
table.init 0 0)
126
+
(func (param $d i32) (result i32) ;; Example of function to be injected into "table"
127
+
local.get 0)
128
+
(elem (;0;) func 3))
129
+
```
130
+
131
+
(**Rationale**: With this approach it is possible to identify without loading the webcil module
132
+
exactly the allocations/table growth/globals which are needed to load the webcil module via
133
+
instantiateStreaming without actually loading the module.)
134
+
135
+
(**Rationale**: Using a new function called fillWebcilTable to fill in the table enables future
136
+
multithreading logic which may require instantiating the table in multiple workers, without
137
+
recopying the memory from the webassembly segment into the memory space.)
138
+
139
+
(**Rationale**: The getWebcilPayload api filling in the TableBase field of the WebcilHeader allows
140
+
the runtime to put a more complex implementation of the relocations scheme into the code which is part
141
+
of the runtime's wasm code, reducing the volume of code needed in each webcil file.)
142
+
143
+
(**Rationale**: Requiring an alignment of 16 bytes allows for both efficient memory usage for loading
144
+
images into linear memory, as well as for allowing for efficient storage of 128 bit vector constants
145
+
within the binary.)
77
146
78
147
### Webcil payload
79
148
@@ -113,11 +182,11 @@ The Webcil headers consist of a Webcil header followed by a sequence of section
113
182
struct WebcilHeader {
114
183
uint8_t Id[4]; // 'W' 'b' 'I' 'L'
115
184
// 4 bytes
116
-
uint16_t VersionMajor; // 0
185
+
uint16_t VersionMajor; // 0 or 1
117
186
uint16_t VersionMinor; // 0
118
187
// 8 bytes
119
188
uint16_t CoffSections;
120
-
uint16_t Reserved0; // 0
189
+
uint16_t Reserved0; // 0 OR WebCilSection of relocation table
121
190
// 12 bytes
122
191
123
192
uint32_t PeCliHeaderRva;
@@ -130,19 +199,21 @@ struct WebcilHeader {
130
199
};
131
200
```
132
201
133
-
#### Webcil Header (V1 Changes)
134
-
For Webcil V1, the Reserved0 field may be used to store a 1-based index which corresponds to a
135
-
base reloc section.
136
-
```
137
-
uint16_t Reserved0; // 0, or 1-based index of .reloc webcil section
138
-
```
139
-
140
202
The Webcil header starts with the magic characters 'W' 'b' 'I' 'L' followed by the version in major
141
203
minor format (must be 0 and 0). Then a count of the section headers and two reserved bytes.
142
204
143
205
The next pairs of integers are a subset of the PE Header data directory specifying the RVA and size
144
206
of the CLI header, as well as the directory entry for the PE debug directory.
145
207
208
+
#### Webcil Header (V1.0 Changes)
209
+
For Webcil V1, the Reserved0 field may be used to store a 1-based index which corresponds to a
210
+
base reloc section.
211
+
```
212
+
uint16_t Reserved0; // 0, or 1-based index of .reloc webcil section
213
+
```
214
+
215
+
The header structure has an additional `uint32_t` field called TableBase which is filled in with the
216
+
value of the tableBase global value during execution of `getWebcilPayload`.
146
217
147
218
#### Section header table
148
219
@@ -191,18 +262,36 @@ Lossless conversion from Webcil back to PE is not intended to be supported. The
191
262
documented in order to support diagnostic tooling and utilities such as decompilers, disassemblers,
192
263
file identification utilities, dependency analyzers, etc.
193
264
265
+
### Special sections
194
266
195
-
### Webcil V1 (Base Relocations)
267
+
####Webcil V1 (Base Relocations)
196
268
It is possible to specify base relocations in the standard PE base relocation format in Webcil V1.
197
-
Relocations are grouped by page (default 4kb), and each relocation entry is a `uint16_t` containing:
198
-
199
-
- Relocation Type (upper 4 bits)
200
-
- IMAGE_REL_BASED_DIR64 (wasm64)
201
-
- IMAGE_REL_BASED_HIGHLOW (wasm32)
202
-
- IMAGE_REL_BASED_WASM32_TABLE (wasm32)
203
-
- IMAGE_REL_BASED_WASM64_TABLE (wasm64)
204
-
- Offset (lower 12 bits)
269
+
Valid relocation types
270
+
| Relocation type | Value | Supported Wasm bitness | Purpose |
271
+
| --- | --- | --- | --- |
272
+
| IMAGE_REL_BASED_DIR64 | 10 | 64 bit only | Representing a pointer value of the loaded image in a 64 bit WebAssembly Memory |
273
+
| IMAGE_REL_BASED_HIGHLOW | 3 | 32 bit only | Representing a pointer value of the loaded image in a 32 bit WebAssembly Memory |
274
+
| IMAGE_REL_BASED_WASM32_TABLE | 12 | All | Representing a "function pointer" for 32 bits, and the minimal size for a function pointer on 64 bit webassembly (table sizes are limited to 32bits of entries even on 64 bit WebAssembly scenarios) |
275
+
| IMAGE_REL_BASED_WASM64_TABLE | 13 | All | Representing a "function pointer" for 64 bits scenarios, but available on 32bit platform since its not impractical to implement. |
276
+
| IMAGE_REL_BASED_ABSOLUTE | 0 | All | Used to put padding into the relocation block. |
205
277
206
278
`IMAGE_REL_BASED_WASM{32, 64}_TABLE` relocations represent a "table base offset" fixup; They should be used to indicate places
207
279
where function pointer table indices need to be offset after the Webcil payload has been loaded by the runtime. The offset will
208
280
be dependent on the state of the table when an implementation's loader loads a Webcil module.
281
+
282
+
The phyical layout of the section will be series of blocks. Each block must be is 4 byte aligned
283
+
284
+
```c
285
+
struct IMAGE_BASE_RELOCATION {
286
+
uint32_t VirtualAddress;;
287
+
uint32_t SizeOfBlock;
288
+
};
289
+
```
290
+
291
+
| Field name | Meaning |
292
+
| --- | --- |
293
+
|`VirtualAddress`| RVA into the loaded webcil image |
294
+
|`SizeOfBlock`| Size of the block. This includes the size of the `IMAGE_BASE_RELOCATION` structure. |
295
+
296
+
Each 2 byte word following `IMAGE_BASE_RELOCATION` is decoded as a `uint16_t` where then lower 12 bits
297
+
indicate an offset from the `VirtualAddress` of the block, and the high 4 bits represents the relocation type.
0 commit comments