Skip to content

Refactor the AST of types in the witx crate #391

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.

Sign up for GitHub

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

Merged
merged 10 commits into from
Feb 11, 2021
Merged

Refactor the AST of types in the witx crate #391

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
3bcf82b
Rename `Array` to `List`
alexcrichton Feb 8, 2021
1fc1dd2
Rename structs to records
alexcrichton Feb 8, 2021
e6451fb
Add initial support for `variant` type
alexcrichton Feb 8, 2021
ce0c8c1
Remove `IntDatatype`
alexcrichton Feb 8, 2021
01360e1
Implement enums in terms of `Variant`
alexcrichton Feb 8, 2021
616dac9
Define `Flags` in terms of integers
alexcrichton Feb 8, 2021
de0b5ff
Represent strings as lists of `char` internally
alexcrichton Feb 8, 2021
cf29081
Implement Union in terms of Variant
alexcrichton Feb 8, 2021
a958d6a
Embed type-hint declarations in AST payloads
alexcrichton Feb 8, 2021
2cdd6be
Address some review feedback
alexcrichton Feb 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 87 additions & 94 deletions phases/ephemeral/docs.md
View file
Open in desktop

Large diffs are not rendered by default.

92 changes: 45 additions & 47 deletions phases/ephemeral/witx/typenames.witx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@

;;; Identifiers for clocks.
(typename $clockid
(enum u32
(enum (@witx tag u32)
;;; The clock measuring real time. Time value zero corresponds with
;;; 1970-01-01T00:00:00Z.
$realtime
Expand All @@ -35,7 +35,7 @@
;;; API; some are used in higher-level library layers, and others are provided
;;; merely for alignment with POSIX.
(typename $errno
(enum u16
(enum (@witx tag u16)
;;; No error occurred. System call completed successfully.
$success
;;; Argument list too long.
Expand Down Expand Up @@ -195,7 +195,7 @@

;;; File descriptor rights, determining which actions may be performed.
(typename $rights
(flags u64
(flags (@witx bitflags u64)
;;; The right to invoke `fd_datasync`.
;;
;;; If `path_open` is set, includes the right to invoke
Expand Down Expand Up @@ -286,7 +286,7 @@

;;; A region of memory for scatter/gather reads.
(typename $iovec
(struct
(record
;;; The address of the buffer to be filled.
(field $buf (@witx pointer u8))
;;; The length of the buffer to be filled.
Expand All @@ -296,23 +296,23 @@

;;; A region of memory for scatter/gather writes.
(typename $ciovec
(struct
(record
;;; The address of the buffer to be written.
(field $buf (@witx const_pointer u8))
;;; The length of the buffer to be written.
(field $buf_len $size)
)
)

(typename $iovec_array (array $iovec))
(typename $ciovec_array (array $ciovec))
(typename $iovec_array (list $iovec))
(typename $ciovec_array (list $ciovec))

;;; Relative offset within a file.
(typename $filedelta s64)

;;; The position relative to which to set the offset of the file descriptor.
(typename $whence
(enum u8
(enum (@witx tag u8)
;;; Seek relative to start-of-file.
$set
;;; Seek relative to current position.
Expand All @@ -323,12 +323,10 @@
)

;;; A reference to the offset of a directory entry.
(typename $dircookie
(int u64
;;; In an `fd_readdir` call, this value signifies the start of the directory.
(const $start 0)
)
)
(typename $dircookie u64)

;;; In an `fd_readdir` call, this value signifies the start of the directory.
(@witx const $dircookie $start 0)

;;; The type for the `dirent::d_namlen` field of `dirent`.
(typename $dirnamlen u32)
Expand All @@ -338,7 +336,7 @@

;;; The type of a file descriptor or file.
(typename $filetype
(enum u8
(enum (@witx tag u8)
;;; The type of the file descriptor or file is unknown or is different from any of the other types specified.
$unknown
;;; The file descriptor or file refers to a block device inode.
Expand All @@ -362,7 +360,7 @@

;;; A directory entry.
(typename $dirent
(struct
(record
;;; The offset of the next directory entry stored in this directory.
(field $d_next $dircookie)
;;; The serial number of the file referred to by this directory entry.
Expand All @@ -376,7 +374,7 @@

;;; File or memory access pattern advisory information.
(typename $advice
(enum u8
(enum (@witx tag u8)
;;; The application has no advice to give on its behavior with respect to the specified data.
$normal
;;; The application expects to access the specified data sequentially from lower offsets to higher offsets.
Expand All @@ -394,7 +392,7 @@

;;; File descriptor flags.
(typename $fdflags
(flags u16
(flags (@witx bitflags u16)
;;; Append mode: Data written to the file is always appended to the file's end.
$append
;;; Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized.
Expand All @@ -412,7 +410,7 @@

;;; File descriptor attributes.
(typename $fdstat
(struct
(record
;;; File type.
(field $fs_filetype $filetype)
;;; File descriptor flags.
Expand All @@ -431,7 +429,7 @@

;;; Which file time attributes to adjust.
(typename $fstflags
(flags u16
(flags (@witx bitflags u16)
;;; Adjust the last data access timestamp to the value stored in `filestat::atim`.
$atim
;;; Adjust the last data access timestamp to the time of clock `clockid::realtime`.
Expand All @@ -445,15 +443,15 @@

;;; Flags determining the method of how paths are resolved.
(typename $lookupflags
(flags u32
(flags (@witx bitflags u32)
;;; As long as the resolved path corresponds to a symbolic link, it is expanded.
$symlink_follow
)
)

;;; Open flags used by `path_open`.
(typename $oflags
(flags u16
(flags (@witx bitflags u16)
;;; Create file if it does not exist.
$create
;;; Fail if not a directory.
Expand All @@ -472,7 +470,7 @@
;;; file in a filesystem, and don't fully reflect all the conditions
;;; which determine whether a given WASI program can access the file.
(typename $permissions
(flags u8
(flags (@witx bitflags u8)
;;; For files, permission to read the file.
;;; For directories, permission to do `readdir` and access files
;;; within the directory.
Expand Down Expand Up @@ -501,7 +499,7 @@

;;; File attributes.
(typename $filestat
(struct
(record
;;; Device ID of device containing the file.
(field $dev $device)
;;; File serial number.
Expand Down Expand Up @@ -529,7 +527,7 @@

;;; Type of a subscription to an event or its occurrence.
(typename $eventtype
(enum u8
(enum (@witx tag u8)
;;; The time value of clock `subscription_clock::id` has
;;; reached timestamp `subscription_clock::timeout`.
$clock
Expand All @@ -545,7 +543,7 @@
;;; The state of the file descriptor subscribed to with
;;; `eventtype::fd_read` or `eventtype::fd_write`.
(typename $eventrwflags
(flags u16
(flags (@witx bitflags u16)
;;; The peer of this socket has closed or disconnected.
$fd_readwrite_hangup
)
Expand All @@ -554,7 +552,7 @@
;;; The contents of an `event` when type is `eventtype::fd_read` or
;;; `eventtype::fd_write`.
(typename $event_fd_readwrite
(struct
(record
;;; The number of bytes available for reading or writing.
(field $nbytes $filesize)
;;; The state of the file descriptor.
Expand All @@ -564,16 +562,16 @@

;;; The contents of an `event`.
(typename $event_u
(union $eventtype
(field $fd_read $event_fd_readwrite)
(field $fd_write $event_fd_readwrite)
(empty $clock)
(variant (@witx tag $eventtype)
(case $fd_read $event_fd_readwrite)
(case $fd_write $event_fd_readwrite)
(case $clock)
)
)

;;; An event that occurred.
(typename $event
(struct
(record
;;; User-provided value that got attached to `subscription::userdata`.
(field $userdata $userdata)
;;; If non-zero, an error that occurred while processing the subscription request.
Expand All @@ -586,7 +584,7 @@
;;; Flags determining how to interpret the timestamp provided in
;;; `subscription_clock::timeout`.
(typename $subclockflags
(flags u16
(flags (@witx bitflags u16)
;;; If set, treat the timestamp provided in
;;; `subscription_clock::timeout` as an absolute timestamp of clock
;;; `subscription_clock::id`. If clear, treat the timestamp
Expand All @@ -598,7 +596,7 @@

;;; The contents of a `subscription` when type is `eventtype::clock`.
(typename $subscription_clock
(struct
(record
;;; The clock against which to compare the timestamp.
(field $id $clockid)
;;; The absolute or relative timestamp.
Expand All @@ -614,24 +612,24 @@
;;; The contents of a `subscription` when type is type is
;;; `eventtype::fd_read` or `eventtype::fd_write`.
(typename $subscription_fd_readwrite
(struct
(record
;;; The file descriptor on which to wait for it to become ready for reading or writing.
(field $fd $fd)
)
)

;;; The contents of a `subscription`.
(typename $subscription_u
(union $eventtype
(field $clock $subscription_clock)
(field $fd_read $subscription_fd_readwrite)
(field $fd_write $subscription_fd_readwrite)
(union (@witx tag $eventtype)
$subscription_clock
$subscription_fd_readwrite
$subscription_fd_readwrite
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not immediately clear why some unions such as event_u are migrated to variant and others, such as subscription_u here, are left as union.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The desugaring is a bit tricky with the current ABI, but I generally tried to keep things as union where possible. By using @witx tag the union's types must all mattch up exactly with the variants of the tag (which should be an enum).

One place this was tripped up though was the empty case parsing for unions. That was where one entry of the union didn't have any payload. This didn't have any translation to this updated union syntax where it must be a set of types that are union'd, so anything using empty was switch to the explicit variant.

In general it doesn't matter too too much except from a readability perspective since this all desugars to the same thing in the AST, which is to say a tagged variant.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is variant a superset of the functionality of union? If so, I think it's ok to migrate to variant over time. To help readers, I do want to aim for a single syntax, but we can finish the migration later.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is, yeah, mostly because variant is the actual thing in the AST whereas union is just syntax sugar as seen here .

This will hopefully become less important over time as @witx tag is migrated away from perhaps? Otherwise though there could perhaps be more syntax sugar for a union where one of the cases is empty.

)
)

;;; Subscription to an event.
(typename $subscription
(struct
(record
;;; User-provided value that is attached to the subscription in the
;;; implementation and returned through `event::userdata`.
(field $userdata $userdata)
Expand All @@ -645,7 +643,7 @@

;;; Flags provided to `sock_recv`.
(typename $riflags
(flags u16
(flags (@witx bitflags u16)
;;; Returns the message without removing it from the socket's receive queue.
$recv_peek
;;; On byte-stream sockets, block until the full amount of data can be returned.
Expand All @@ -655,7 +653,7 @@

;;; Flags returned by `sock_recv`.
(typename $roflags
(flags u16
(flags (@witx bitflags u16)
;;; Returned by `sock_recv`: Message data has been truncated.
$recv_data_truncated
)
Expand All @@ -667,7 +665,7 @@

;;; Which channels on a socket to shut down.
(typename $sdflags
(flags u8
(flags (@witx bitflags u8)
;;; Disables further receive operations.
$rd
;;; Disables further send operations.
Expand All @@ -677,24 +675,24 @@

;;; Identifiers for preopened capabilities.
(typename $preopentype
(enum u8
(enum (@witx tag u8)
;;; A pre-opened directory.
$dir
)
)

;;; The contents of a `prestat` when its type is `preopentype::dir`.
(typename $prestat_dir
(struct
(record
;;; The length of the directory name for use with `fd_prestat_dir_name`.
(field $pr_name_len $size)
)
)

;;; Information about a pre-opened capability.
(typename $prestat
(union $preopentype
(union (@witx tag $preopentype)
;;; When type is `preopentype::dir`:
(field $dir $prestat_dir)
$prestat_dir
)
)
4 changes: 2 additions & 2 deletions phases/ephemeral/witx/wasi_ephemeral_args.witx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@
;;; Read command-line argument data.
;;; The size of the array should match that returned by `sizes_get`
(@interface func (export "get")
(param $argv (@witx pointer (@witx pointer char8)))
(param $argv_buf (@witx pointer char8))
(param $argv (@witx pointer (@witx pointer (@witx char8))))
(param $argv_buf (@witx pointer (@witx char8)))
(result $error $errno)
)

Expand Down
4 changes: 2 additions & 2 deletions phases/ephemeral/witx/wasi_ephemeral_environ.witx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@
;;; Read environment variable data.
;;; The sizes of the buffers should match that returned by `sizes_get`.
(@interface func (export "get")
(param $environ (@witx pointer (@witx pointer char8)))
(param $environ_buf (@witx pointer char8))
(param $environ (@witx pointer (@witx pointer (@witx char8))))
(param $environ_buf (@witx pointer (@witx char8)))
(result $error $errno)
)

Expand Down
2 changes: 1 addition & 1 deletion phases/ephemeral/witx/wasi_ephemeral_fd.witx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@
(@interface func (export "prestat_dir_name")
(param $fd $fd)
;;; A buffer into which to write the preopened directory name.
(param $path (@witx pointer char8))
(param $path (@witx pointer (@witx char8)))
(param $path_len $size)
(result $error $errno)
)
Expand Down
2 changes: 1 addition & 1 deletion phases/ephemeral/witx/wasi_ephemeral_path.witx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@
;;; The path of the symbolic link from which to read.
(param $path string)
;;; The buffer to which to write the contents of the symbolic link.
(param $buf (@witx pointer char8))
(param $buf (@witx pointer (@witx char8)))
(param $buf_len $size)
(result $error $errno)
;;; The number of bytes placed in the buffer.
Expand Down
Loading