diff --git a/design/witx-type-representation.md b/design/witx-type-representation.md new file mode 100644 index 00000000..1a5d7035 --- /dev/null +++ b/design/witx-type-representation.md @@ -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 @ offset 0 +buf_len: size @ offset 4 + ++------+------+------+------+------+------+------+------+ +| 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 | ++------+------+------+------+------+------+------+------+ +``` + +# Pointer and List + +A `Pointer` and `List` are both just `Pointer`s. A `Pointer`'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 + ++------+------+------+------+ +| 0x00 | 0x00 | 0x00 | 0x00 | ++------+------+------+------+ +^ a number, that represents another position in RAM that leads to the data. +```