-
Notifications
You must be signed in to change notification settings - Fork 280
Create witx-type-representation.md #318
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,91 @@ | ||
# Witx Type Representation | ||
|
||
In Witx, each type corresponds to a lower-level type. For example, the `size` | ||
type resolves to a `u32`, the `errno` type resolves to an `Enum(u16)`, and | ||
more. Detailed below is each type, and what they correspond to in the | ||
WebAssembly type system. | ||
|
||
## u8/u16/u32/u64/s64 | ||
|
||
These are C-style `uint8_t`s, `uint16_t`s, `uint32_t`s, `uint64_t`s, and | ||
`int64_t`s. More information about the signedness-aware integer types [can be | ||
found here](https://github.com/WebAssembly/interface-types/blob/master/proposals/interface-types/Explainer.md#integers). | ||
|
||
The endian-ness of these types are **little endian**, as _all_ types in the WebAssembly | ||
type system are little endian. [See here for more information](https://github.com/WebAssembly/design/issues/786#issuecomment-244548105). | ||
|
||
# Record | ||
|
||
A `Record` is a type that takes up some contiguous amount of memory, with each | ||
field taking up a specific amount of reserved bytes. Interpreting the bytes as | ||
one of the types in Witx will yield a usable value. | ||
|
||
``` | ||
iovec | ||
|
||
buf: Pointer<u8> @ offset 0 | ||
buf_len: size @ offset 4 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The offset may be 4 or 8 depends on sizeof pointer There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It seems that the docs don't mention this distinction - I'm unsure if it's within scope of this PR to mention it if the docs don't. |
||
|
||
+------+------+------+------+------+------+------+------+ | ||
| 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | | ||
+------+------+------+------+------+------+------+------+ | ||
^buf ^buf_len | ||
``` | ||
|
||
The `Size` of a `Record` refers to how many contiguous bytes it takes up in | ||
memory. | ||
|
||
The `Alignment` of a `Record` refers to the byte boundary that the record must | ||
be on in memory. For example, the above `iovec` could only ever get allocated | ||
to a memory address that is divisible by 4, because the alignment is 4. | ||
|
||
# Variant | ||
|
||
A `Variant` is a type which uses some bits to determine which variant of | ||
the variant the data will be. The data is simply inserted as is with whatever | ||
type it may be. | ||
|
||
``` | ||
errno: Variant | ||
+------+------+------+------+ | ||
| 0x00 | 0x00 | 0x00 | 0x15 | | ||
+------+------+------+------+ | ||
^ fault | ||
``` | ||
|
||
``` | ||
subscription_u | ||
|
||
+------+------+------+------+------+------+------+------+ | ||
| 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | | ||
+------+------+------+------+------+------+------+------+ | ||
^ padding due to the alignment of the variant ^tag_size | ||
|
||
cont. 32 bytes for the variant's data | ||
+------+------+------+------+------+------+------+------+ | ||
| 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | | ||
+------+------+------+------+------+------+------+------+ | ||
| 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | | ||
+------+------+------+------+------+------+------+------+ | ||
| 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | | ||
+------+------+------+------+------+------+------+------+ | ||
``` | ||
monoclex marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
# Pointer<T> and List<T> | ||
|
||
A `Pointer<T>` and `List<T>` are both just `Pointer<T>`s. A `Pointer<T>`'s | ||
size is guaranteed to be 8 bytes, but if on a 32 bit architecture it will only | ||
use 4 of the 8 bytes. The pointers themselves are 32 bit, as wasm32 is the only | ||
ABI currently implemented. In the future when the specification for wasm64 is | ||
done, that will change. The data stored in one of these types is exactly enough | ||
to point to some data in RAM. When the pointer is dereferenced, the data stored | ||
at that location will be an unknown contiguous amount of `T`s. | ||
|
||
``` | ||
Pointer<u8> | ||
|
||
+------+------+------+------+ | ||
| 0x00 | 0x00 | 0x00 | 0x00 | | ||
+------+------+------+------+ | ||
^ a number, that represents another position in RAM that leads to the data. | ||
``` |
Uh oh!
There was an error while loading. Please reload this page.