Skip to content

Commit 0c4b9ec

Browse files
SirJosh3917SirJosh3917
SirJosh3917
authored and
SirJosh3917
committed
take suggestions from the review
1 parent 19a57f7 commit 0c4b9ec

File tree

1 file changed

+67
-32
lines changed

1 file changed

+67
-32
lines changed

design/witx-type-representation.md

Lines changed: 67 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,45 @@
11
# Witx Type Representation
2-
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 resolve to in memory.
32

4-
# u8/u16/u32/u64/s64
5-
These are C-style `uint8_t`s, `uint16_t`s, `uint32_t`s, `uint64_t`s, and `int64_t`s. In the .NET world, they may be more recognizable as an `byte` (in C# this is an unsigned `byte` if you're coming from Java), `ushort`, `uint`, `ulong`, and `long`. These are typically little-endian, although it may not be necessary to know that.
3+
In Witx, each type corresponds to a lower-level type. For example, the `size`
4+
type resolves to a `u32`, the `errno` type resolves to an `Enum(u16)`, and
5+
more. Detailed below is each type, and what they correspond to in the
6+
WebAssembly type system.
7+
8+
## u8/u16/u32/u64/s64
9+
10+
These are C-style `uint8_t`s, `uint16_t`s, `uint32_t`s, `uint64_t`s, and
11+
`int64_t`s. More information about the signedness-aware integer types [can be
12+
found here](https://github.com/WebAssembly/interface-types/blob/master/proposals/interface-types/Explainer.md#integers).
13+
14+
The endian-ness of these types are **little endian**, as _all_ types in the WebAssembly
15+
type system are little endian. [See here for more information](https://github.com/WebAssembly/design/issues/786#issuecomment-244548105).
616

717
# Enum(T)
8-
An `Enum(T)` is, unlike a Rust Enum(T), simply is a `T`. However, the value of T can only be one of the specific variants of the enum. This type lends itself to describing when something can only be one of the enumerations in the group (for example, in a group of Dogs and Cats, you may have an enum representing either a Dog or a Cat).
18+
19+
An `Enum(T)` is simply is a `T`. However, the value of T can only be one of the
20+
specific variants of the enum. This type lends itself to describing when
21+
something can only be one of the enumerations in the group (for example, in a
22+
group of Dogs and Cats, you may have an enum representing either a Dog or a
23+
Cat).
924

1025
```
1126
errno: Enum(u32)
12-
+-----------------+-----------------+-----------------+-----------------+
13-
| 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 1 0 1 0 1 |
14-
+-----------------+-----------------+-----------------+-----------------+
27+
+------+------+------+------+
28+
| 0x00 | 0x00 | 0x00 | 0x15 |
29+
+------+------+------+------+
1530
^ fault
1631
```
1732

18-
(`clockid` despite only representing 4 values is an `Enum(u32)`. This is for ABI compatibility.)
33+
(`clockid` despite only representing 4 values is an `Enum(u32)`. This is
34+
primarily for ABI compatibility, and future-proofing.)
1935

2036
# Flags(T)
21-
A `Flags(T)` datatype takes up exactly a `T` in memory, similar to `Enum(T)`. However, each variant of a `Flags(T)` will take up exactly one bit in the data. This allows the usage of bitwise AND, bitwise OR, and bitwise NOT operators to combine, check, or exclude specific values in the flag very easily. This type lends itself to describing capabilities.
37+
38+
A `Flags(T)` datatype takes up exactly a `T` in memory, similar to `Enum(T)`.
39+
However, each variant of a `Flags(T)` will take up exactly one bit in the data.
40+
This allows the usage of bitwise AND, bitwise OR, and bitwise NOT operators to
41+
combine, check, or exclude specific values in the flag very easily. This type
42+
lends itself to describing capabilities.
2243

2344
```
2445
oflags: Flags(u16)
@@ -34,53 +55,67 @@ oflags: Flags(u16)
3455
```
3556

3657
# Struct
37-
A `Struct` is a type that takes up some contiguous amount of blocks in 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.
58+
59+
A `Struct` is a type that takes up some contiguous amount of memory, with each
60+
field taking up a specific amount of reserved bytes. Interpreting the bytes as
61+
one of the types in Witx will yield a usable value.
3862

3963
```
4064
iovec
4165
4266
buf: Pointer<u8> @ offset 0
4367
buf_len: size @ offset 4
4468
45-
+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
46-
| 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 |
47-
+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
48-
^buf ^buf_len
69+
+------+------+------+------+------+------+------+------+
70+
| 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 |
71+
+------+------+------+------+------+------+------+------+
72+
^buf ^buf_len
4973
```
5074

51-
The `Size` of a `Struct` refers to how many contiguous bytes it takes up in memory.
75+
The `Size` of a `Struct` refers to how many contiguous bytes it takes up in
76+
memory.
5277

5378
The `Alignment` of a `Struct` refers to <X>.
5479

5580
# Union
56-
A `Union` is a type which uses `tag_size` bytes to determine which variant of the union the data will be. The data is simply inserted as is with whatever type it may be.
81+
82+
A `Union` is a type which uses `tag_size` bytes to determine which variant of
83+
the union the data will be. The data is simply inserted as is with whatever
84+
type it may be.
5785

5886
```
5987
subscription_u
6088
61-
+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
62-
| 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 |
63-
+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
64-
^ padding due to the alignment of the union ^tag_size
89+
+------+------+------+------+------+------+------+------+
90+
| 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 |
91+
+------+------+------+------+------+------+------+------+
92+
^ padding due to the alignment of the union ^tag_size
6593
6694
cont. 32 bytes for the union's data
67-
+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
68-
| 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 |
69-
+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
70-
| 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 |
71-
+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
72-
| 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 |
73-
+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
95+
+------+------+------+------+------+------+------+------+
96+
| 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 |
97+
+------+------+------+------+------+------+------+------+
98+
| 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 |
99+
+------+------+------+------+------+------+------+------+
100+
| 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 |
101+
+------+------+------+------+------+------+------+------+
74102
```
75103

76104
# Pointer<T> and Array<T>
77-
A `Pointer<T>` and `Array<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 be 4 bytes. 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 a contiguous amount of `T`s. // how to get length? is there one for ArrayT?
105+
106+
A `Pointer<T>` and `Array<T>` are both just `Pointer<T>`s. A `Pointer<T>`'s
107+
size is guaranteed to be 8 bytes, but if on a 32 bit architecture it will only
108+
use 4 of the 8 bytes. The pointers themselves are 32 bit, as wasm32 is the only
109+
ABI currently implemented. In the future when the specification for wasm64 is
110+
done, that will change. The data stored in one of these types is exactly enough
111+
to point to some data in RAM. When the pointer is dereferenced, the data stored
112+
at that location will be an unknown contiguous amount of `T`s.
78113

79114
```
80115
Pointer<u8>
81116
82-
+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
83-
| 0 0 0 0 0 1 0 0 | 0 0 1 0 1 1 0 0 | 0 0 0 1 1 1 0 0 | 0 0 1 1 0 1 0 0 | 1 0 0 1 0 0 0 0 | 0 0 0 0 0 1 0 0 | 0 0 0 0 1 0 0 1 | 0 0 0 1 0 0 0 0 |
84-
+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+-----------------+
85-
^ makes up a value, which when dereferenced leads to another point in RAM with the actual data
117+
+------+------+------+------+------+------+------+------+
118+
| 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 |
119+
+------+------+------+------+------+------+------+------+
120+
^ a number, that represents another position in RAM that leads to the data.
86121
```

0 commit comments

Comments
 (0)