From ca38d969733bdde5d37f828c8b8f53595668fd1e Mon Sep 17 00:00:00 2001 From: SirJosh3917 Date: Tue, 11 May 2021 01:45:17 -0400 Subject: [PATCH] Update terminology to be modern --- design/witx-type-representation.md | 78 +++++++++--------------------- 1 file changed, 24 insertions(+), 54 deletions(-) diff --git a/design/witx-type-representation.md b/design/witx-type-representation.md index efff4da5..1a5d7035 100644 --- a/design/witx-type-representation.md +++ b/design/witx-type-representation.md @@ -14,49 +14,9 @@ found here](https://github.com/WebAssembly/interface-types/blob/master/proposals 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). -# Enum(T) +# Record -An `Enum(T)` is 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). - -``` -errno: Enum(u32) -+------+------+------+------+ -| 0x00 | 0x00 | 0x00 | 0x15 | -+------+------+------+------+ -^ fault -``` - -(`clockid` despite only representing 4 values is an `Enum(u32)`. This is -primarily for ABI compatibility, and future-proofing.) - -# Flags(T) - -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. - -``` -oflags: Flags(u16) - -+-----------------+-----------------+ -| 0 1 1 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | -+-----------------+-----------------+ - ^ ^ ^ ^ - | | | trunc - | | excl - | directory - creat -``` - -# Struct - -A `Struct` is a type that takes up some contiguous amount of memory, with each +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. @@ -72,26 +32,36 @@ buf_len: size @ offset 4 ^buf ^buf_len ``` -The `Size` of a `Struct` refers to how many contiguous bytes it takes up in +The `Size` of a `Record` refers to how many contiguous bytes it takes up in memory. -The `Alignment` of a `Struct` refers to . +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. -# Union +# Variant -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 +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 union ^tag_size +^ padding due to the alignment of the variant ^tag_size -cont. 32 bytes for the union's data +cont. 32 bytes for the variant's data +------+------+------+------+------+------+------+------+ | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | +------+------+------+------+------+------+------+------+ @@ -101,9 +71,9 @@ cont. 32 bytes for the union's data +------+------+------+------+------+------+------+------+ ``` -# Pointer and Array +# Pointer and List -A `Pointer` and `Array` are both just `Pointer`s. A `Pointer`'s +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 @@ -114,8 +84,8 @@ at that location will be an unknown contiguous amount of `T`s. ``` Pointer -+------+------+------+------+------+------+------+------+ -| 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | -+------+------+------+------+------+------+------+------+ ++------+------+------+------+ +| 0x00 | 0x00 | 0x00 | 0x00 | ++------+------+------+------+ ^ a number, that represents another position in RAM that leads to the data. ```