Modularize the WASI API.

This splits what was previously "preview" into separate modules.
There's a lot of API evolution still to be done here, and the
groupings presented here may change, but this should help get
things started.

Author: sunfishcode

phases/ephemeral/docs/wasi_ephemeral_preview.md

@@ -0,0 +1,28 @@
+;; WASI Command-line Arguments.
+;;
+;; This is a `witx` file. See [here](https://github.com/WebAssembly/WASI/tree/master/docs/witx.md)
+;; for an explanation of what that means.
+
+(use "typenames.witx")
+
+(module $wasi_ephemeral_args
+  ;;; Linear memory to be accessed by WASI functions that need it.
+  (import "memory" (memory))
+
+  ;;; 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 u8)))
+    (param $argv_buf (@witx pointer u8))
+    (result $error $errno)
+  )
+
+  ;;; Return command-line argument data sizes.
+  (@interface func (export "sizes_get")
+    (result $error $errno)
+    ;;; The number of arguments.
+    (result $argc $size)
+    ;;; The size of the argument string data.
+    (result $argv_buf_size $size)
+  )
+)

phases/ephemeral/witx/wasi_ephemeral_args.witx

@@ -0,0 +1,36 @@
+;; WASI Clocks.
+;;
+;; Some content here is derived from [CloudABI](https://github.com/NuxiNL/cloudabi).
+;;
+;; This is a `witx` file. See [here](https://github.com/WebAssembly/WASI/tree/master/docs/witx.md)
+;; for an explanation of what that means.
+
+(use "typenames.witx")
+
+(module $wasi_ephemeral_clock
+  ;;; Linear memory to be accessed by WASI functions that need it.
+  (import "memory" (memory))
+
+  ;;; Return the resolution of a clock.
+  ;;; Implementations are required to provide a non-zero value for supported clocks. For unsupported clocks, return `WASI_EINVAL`
+  ;;; Note: This is similar to `clock_getres` in POSIX.
+  (@interface func (export "res_get")
+    (result $error $errno)
+    ;;; The clock for which to return the resolution.
+    (param $id $clockid)
+    ;;; The resolution of the clock.
+    (result $resolution $timestamp)
+  )
+
+  ;;; Return the time value of a clock.
+  ;;; Note: This is similar to `clock_gettime` in POSIX.
+  (@interface func (export "time_get")
+    ;;; The clock for which to return the time.
+    (param $id $clockid)
+    ;;; The maximum lag (exclusive) that the returned time value may have, compared to its actual value.
+    (param $precision $timestamp)
+    (result $error $errno)
+    ;;; The time value of the clock.
+    (result $time $timestamp)
+  )
+)

phases/ephemeral/witx/wasi_ephemeral_clock.witx

@@ -0,0 +1,28 @@
+;; WASI Environment Variables.
+;;
+;; This is a `witx` file. See [here](https://github.com/WebAssembly/WASI/tree/master/docs/witx.md)
+;; for an explanation of what that means.
+
+(use "typenames.witx")
+
+(module $wasi_ephemeral_environ
+  ;;; Linear memory to be accessed by WASI functions that need it.
+  (import "memory" (memory))
+
+  ;;; 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 u8)))
+    (param $environ_buf (@witx pointer u8))
+    (result $error $errno)
+  )
+
+  ;;; Return command-line argument data sizes.
+  (@interface func (export "sizes_get")
+    (result $error $errno)
+    ;;; The number of arguments.
+    (result $argc $size)
+    ;;; The size of the argument string data.
+    (result $argv_buf_size $size)
+  )
+)

phases/ephemeral/witx/wasi_ephemeral_environ.witx

@@ -0,0 +1,242 @@
+;; WASI I/O.
+;;
+;; Some content here is derived from [CloudABI](https://github.com/NuxiNL/cloudabi).
+;;
+;; This is a `witx` file. See [here](https://github.com/WebAssembly/WASI/tree/master/docs/witx.md)
+;; for an explanation of what that means.
+
+(use "typenames.witx")
+
+(module $wasi_ephemeral_fd
+  ;;; Linear memory to be accessed by WASI functions that need it.
+  (import "memory" (memory))
+
+  ;;; Provide file advisory information on a file descriptor.
+  ;;; Note: This is similar to `posix_fadvise` in POSIX.
+  (@interface func (export "advise")
+    (param $fd $fd)
+    ;;; The offset within the file to which the advisory applies.
+    (param $offset $filesize)
+    ;;; The length of the region to which the advisory applies.
+    (param $len $filesize)
+    ;;; The advice.
+    (param $advice $advice)
+    (result $error $errno)
+  )
+
+  ;;; Force the allocation of space in a file.
+  ;;; Note: This is similar to `posix_fallocate` in POSIX.
+  (@interface func (export "allocate")
+    (param $fd $fd)
+    ;;; The offset at which to start the allocation.
+    (param $offset $filesize)
+    ;;; The length of the area that is allocated.
+    (param $len $filesize)
+    (result $error $errno)
+  )
+
+  ;;; Close a file descriptor.
+  ;;; Note: This is similar to `close` in POSIX.
+  (@interface func (export "close")
+    (param $fd $fd)
+    (result $error $errno)
+  )
+
+  ;;; Synchronize the data of a file to disk.
+  ;;; Note: This is similar to `fdatasync` in POSIX.
+  (@interface func (export "datasync")
+    (param $fd $fd)
+    (result $error $errno)
+  )
+
+  ;;; Get the attributes of a file descriptor.
+  ;;; Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well as additional fields.
+  (@interface func (export "fdstat_get")
+    (param $fd $fd)
+    (result $error $errno)
+    ;;; The buffer where the file descriptor's attributes are stored.
+    (result $stat $fdstat)
+  )
+
+  ;;; Adjust the flags associated with a file descriptor.
+  ;;; Note: This is similar to `fcntl(fd, F_SETFL, flags)` in POSIX.
+  (@interface func (export "fdstat_set_flags")
+    (param $fd $fd)
+    ;;; The desired values of the file descriptor flags.
+    (param $flags $fdflags)
+    (result $error $errno)
+  )
+
+  ;;; Adjust the rights associated with a file descriptor.
+  ;;; This can only be used to remove rights, and returns `ENOTCAPABLE` if called in a way that would attempt to add rights
+  (@interface func (export "fdstat_set_rights")
+    (param $fd $fd)
+    ;;; The desired rights of the file descriptor.
+    (param $fs_rights_base $rights)
+    (param $fs_rights_inheriting $rights)
+    (result $error $errno)
+  )
+
+  ;;; Return the attributes of an open file.
+  (@interface func (export "filestat_get")
+    (param $fd $fd)
+    (result $error $errno)
+    ;;; The buffer where the file's attributes are stored.
+    (result $buf $filestat)
+  )
+
+  ;;; Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros.
+  ;;; Note: This is similar to `ftruncate` in POSIX.
+  (@interface func (export "filestat_set_size")
+    (param $fd $fd)
+    ;;; The desired file size.
+    (param $size $filesize)
+    (result $error $errno)
+  )
+
+  ;;; Adjust the timestamps of an open file or directory.
+  ;;; Note: This is similar to `futimens` in POSIX.
+  (@interface func (export "filestat_set_times")
+    (param $fd $fd)
+    ;;; The desired values of the data access timestamp.
+    (param $atim $timestamp)
+    ;;; The desired values of the data modification timestamp.
+    (param $mtim $timestamp)
+    ;;; A bitmask indicating which timestamps to adjust.
+    (param $fst_flags $fstflags)
+    (result $error $errno)
+  )
+
+  ;;; Read from a file descriptor, without using and updating the file descriptor's offset.
+  ;;; Note: This is similar to `preadv` in POSIX.
+  (@interface func (export "pread")
+    (param $fd $fd)
+    ;;; List of scatter/gather vectors in which to store data.
+    (param $iovs $iovec_array)
+    ;;; The offset within the file at which to read.
+    (param $offset $filesize)
+    (result $error $errno)
+    ;;; The number of bytes read.
+    (result $nread $size)
+  )
+
+  ;;; Return a description of the given preopened file descriptor.
+  (@interface func (export "prestat_get")
+    (param $fd $fd)
+    (result $error $errno)
+    ;;; The buffer where the description is stored.
+    (result $buf $prestat)
+  )
+
+  ;;; Return a description of the given preopened file descriptor.
+  (@interface func (export "prestat_dir_name")
+    (param $fd $fd)
+    ;;; A buffer into which to write the preopened directory name.
+    (param $path (@witx pointer u8))
+    (param $path_len $size)
+    (result $error $errno)
+  )
+
+  ;;; Write to a file descriptor, without using and updating the file descriptor's offset.
+  ;;; Note: This is similar to `pwritev` in POSIX.
+  (@interface func (export "pwrite")
+    (param $fd $fd)
+    ;;; List of scatter/gather vectors from which to retrieve data.
+    (param $iovs $ciovec_array)
+    ;;; The offset within the file at which to write.
+    (param $offset $filesize)
+    (result $error $errno)
+    ;;; The number of bytes written.
+    (result $nwritten $size)
+  )
+
+  ;;; Read from a file descriptor.
+  ;;; Note: This is similar to `readv` in POSIX.
+  (@interface func (export "read")
+    (param $fd $fd)
+    ;;; List of scatter/gather vectors to which to store data.
+    (param $iovs $iovec_array)
+    (result $error $errno)
+    ;;; The number of bytes read.
+    (result $nread $size)
+  )
+
+  ;;; Read directory entries from a directory.
+  ;;; When successful, the contents of the output buffer consist of a sequence of
+  ;;; directory entries. Each directory entry consists of a dirent_t object,
+  ;;; followed by dirent_t::d_namlen bytes holding the name of the directory
+  ;;; entry.
+  ;;
+  ;;; This function fills the output buffer as much as possible, potentially
+  ;;; truncating the last directory entry. This allows the caller to grow its
+  ;;; read buffer size in case it's too small to fit a single large directory
+  ;;; entry, or skip the oversized directory entry.
+  (@interface func (export "readdir")
+    (param $fd $fd)
+    ;;; The buffer where directory entries are stored
+    (param $buf (@witx pointer u8))
+    (param $buf_len $size)
+    ;;; The location within the directory to start reading
+    (param $cookie $dircookie)
+    (result $error $errno)
+    ;;; The number of bytes stored in the read buffer. If less than the size of the read buffer, the end of the directory has been reached.
+    (result $bufused $size)
+  )
+
+  ;;; Atomically replace a file descriptor by renumbering another file descriptor.
+  ;;
+  ;;; Due to the strong focus on thread safety, this environment does not provide
+  ;;; a mechanism to duplicate or renumber a file descriptor to an arbitrary
+  ;;; number, like `dup2()`. This would be prone to race conditions, as an actual
+  ;;; file descriptor with the same number could be allocated by a different
+  ;;; thread at the same time.
+  ;;
+  ;;; This function provides a way to atomically renumber file descriptors, which
+  ;;; would disappear if `dup2()` were to be removed entirely.
+  (@interface func (export "renumber")
+    (param $fd $fd)
+    ;;; The file descriptor to overwrite.
+    (param $to $fd)
+    (result $error $errno)
+  )
+
+  ;;; Move the offset of a file descriptor.
+  ;;; Note: This is similar to `lseek` in POSIX.
+  (@interface func (export "seek")
+    (param $fd $fd)
+    ;;; The number of bytes to move.
+    (param $offset $filedelta)
+    ;;; The base from which the offset is relative.
+    (param $whence $whence)
+    (result $error $errno)
+    ;;; The new offset of the file descriptor, relative to the start of the file.
+    (result $newoffset $filesize)
+  )
+
+  ;;; Synchronize the data and metadata of a file to disk.
+  ;;; Note: This is similar to `fsync` in POSIX.
+  (@interface func (export "sync")
+    (param $fd $fd)
+    (result $error $errno)
+  )
+
+  ;;; Return the current offset of a file descriptor.
+  ;;; Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX.
+  (@interface func (export "tell")
+    (param $fd $fd)
+    (result $error $errno)
+    ;;; The current offset of the file descriptor, relative to the start of the file.
+    (result $offset $filesize)
+  )
+
+  ;;; Write to a file descriptor.
+  ;;; Note: This is similar to `writev` in POSIX.
+  (@interface func (export "write")
+    (param $fd $fd)
+    ;;; List of scatter/gather vectors from which to retrieve data.
+    (param $iovs $ciovec_array)
+    (result $error $errno)
+    ;;; The number of bytes written.
+    (result $nwritten $size)
+  )
+)