Create snapshot 1

phases/README.md

@@ -8,24 +8,32 @@
   provides no API stability or versioning. APIs in this directory use
   API module names starting with `wasi_ephemeral_`.
 
-- [`unstable`](unstable): Usable APIs. APIs in `ephemeral` will be
-  occasionally snapshotted and promoted into `unstable`, with approval
+- [`snapshot`](snapshot): Usable APIs. APIs in `ephemeral` will be
+  occasionally snapshotted and promoted into `snapshot`, with approval
   from the Subgroup, considering the overall suitability of the APIs
   themselves, their documentation, test coverage, and availability of
   polyfills when appropriate. Once merged, the API modules will be
   considered stable, though they may be superseded by newer versions.
   Proposals to promote specific APIs should be submitted as Pull Requests
   that:
-   - Move any superseded files out of `unstable` into `old`.
-   - Optionally add polyfills for superseded APIs using `unstable` APIs.
-   - Move all files supporting the APIs out of `ephemeral` into `unstable`.
-   - Rename the API modules from `wasi_ephemeral_` to `wasi_unstable_`
-     and append a version number.
+    1. `git mv` contents of `phases/snapshot/` to
+       `phases/old/snapshot_{old_snapshot_number}`.
+    2. `cp -R` contents of `phases/ephemeral/` into `phases/snapshot/`.
+    3. Rename files copied into `phases/snapshot/` to substitute `ephemeral`
+       for `snapshot` in file names. Append the new snapshot number to each
+         name.
+    4. Update module names given in `.witx` files according to the previous
+       step.
+    5. Update tests in `tools/witx/tests/wasi.rs` to point at new snapshot, and
+       add a test pointing at the just-archived snapshot under `old`.
+    6. Optionally, under `phases/old/snapshot_{old_snapshot_number}, add
+       polyfills for superceded APIs using the new APIs.
+
 
   Pull Requests may also add additional tests, documentation, or
-  polyfills for existing `unstable` APIs.
+  polyfills for existing `snapshot` APIs.
 
-- [`old`](old): When APIs in `current` spec are replaced by new
+- [`old`](old): When APIs in `snapshot` spec are replaced by new
   versions, the old API modules are moved to the `old` directory. When
   possible, `old` APIs may be accompanied by polyfill modules which
   implement their API in terms of newer versions of the API.
@@ -44,7 +52,7 @@ flexibility.
 
 WASI should eventually become a standard at the level of WebAssembly
 itself. Right now, it needs a lot of work before it's ready. The
-`unstable` tree is meant to serve a practical purpose for people who
+`snapshot` tree is meant to serve a practical purpose for people who
 want to work with APIs today, with the understanding that everything
 is still evolving. It's not meant as a replacement for proper
 standardization, which will happen once the overall API is more

phases/unstable/docs/wasi_unstable_preview0.md → phases/snapshot/docs/wasi_unstable_preview1.md

@@ -117,18 +117,22 @@ modules so that embedders need not implement all of it.
 
 Read command-line argument data.
 
-The sizes of the buffers should match that returned by [`__wasi_args_sizes_get()`](#args_sizes_get).
-
 Inputs:
 
 - <a href="#args_get.argv" name="args_get.argv"></a><code>char \*\*<strong>argv</strong></code>
 
     A pointer to a buffer to write the argument pointers.
 
+    The count of elements for the buffer should be at least the value of `argc` returned by [`__wasi_args_sizes_get()`](#args_sizes_get).
+
+    The caller of `__wasi_args_get()` is responsible for allocating an additional element for a terminating NULL pointer, if necessary.
+
 - <a href="#args_get.argv_buf" name="args_get.argv_buf"></a><code>char \*<strong>argv\_buf</strong></code>
 
     A pointer to a buffer to write the argument string data.
 
+    The size of this buffer should be the value of `argv_buf_size` returned by [`__wasi_args_sizes_get()`](#args_sizes_get).
+
 ### <a href="#args_sizes_get" name="args_sizes_get"></a>`__wasi_args_sizes_get()`
 
 Return command-line argument data sizes.
@@ -192,21 +196,25 @@ Outputs:
 
 Read environment variable data.
 
-The sizes of the buffers should match that returned by [`__wasi_environ_sizes_get()`](#environ_sizes_get).
-
 Inputs:
 
 - <a href="#environ_get.environ" name="environ_get.environ"></a><code>char \*\*<strong>environ</strong></code>
 
     A pointer to a buffer to write the environment variable pointers.
 
+    The count of elements for the buffer should be at least the value of `environ_count` returned by [`__wasi_environ_sizes_get()`](#environ_sizes_get).
+
+    The caller of `__wasi_environ_get()` is responsible for allocating an additional element for a terminating NULL pointer, if necessary.
+
 - <a href="#environ_get.environ_buf" name="environ_get.environ_buf"></a><code>char \*<strong>environ\_buf</strong></code>
 
     A pointer to a buffer to write the environment variable string data.
 
+    The size of this buffer should be the value of `environ_buf_size` returned by [`__wasi_environ_sizes_get()`](#environ_sizes_get).
+
 ### <a href="#environ_sizes_get" name="environ_sizes_get"></a>`__wasi_environ_sizes_get()`
 
-Return command-line argument data sizes.
+Return enviroment variable data sizes.
 
 Outputs:
 
@@ -1799,7 +1807,7 @@ Members:
 
     The address and length of the buffer to be filled.
 
-### <a href="#linkcount" name="linkcount"></a>`__wasi_linkcount_t` (`uint32_t`)
+### <a href="#linkcount" name="linkcount"></a>`__wasi_linkcount_t` (`uint64_t`)
 
 Number of hard links to an inode.
 
@@ -2329,6 +2337,10 @@ Used by [`__wasi_fd_seek()`](#fd_seek).
 
 Possible values:
 
+- <a href="#whence.set" name="whence.set"></a>**`__WASI_WHENCE_SET`**
+
+    Seek relative to start-of-file.
+
 - <a href="#whence.cur" name="whence.cur"></a>**`__WASI_WHENCE_CUR`**
 
     Seek relative to current position.
@@ -2337,7 +2349,3 @@ Possible values:
 
     Seek relative to end-of-file.
 
-- <a href="#whence.set" name="whence.set"></a>**`__WASI_WHENCE_SET`**
-
-    Seek relative to start-of-file.
-

phases/unstable/witx/typenames.witx → phases/snapshot/witx/typenames.witx

@@ -305,16 +305,18 @@
 ;; The position relative to which to set the offset of the file descriptor.
 (typename $whence_t
   (enum u8
+    ;; Seek relative to start-of-file.
+    $WHENCE_SET
     ;; Seek relative to current position.
     $WHENCE_CUR
     ;; Seek relative to end-of-file.
     $WHENCE_END
-    ;; Seek relative to start-of-file.
-    $WHENCE_SET
   )
 )
 
 ;; A reference to the offset of a directory entry.
+;;
+;; The value 0 signifies the start of the directory.
 (typename $dircookie_t u64)
 
 ;; The type for the $d_namlen field of $dirent_t.
@@ -451,7 +453,7 @@
 )
 
 ;; Number of hard links to an inode.
-(typename $linkcount_t u32)
+(typename $linkcount_t u64)
 
 ;; File attributes.
 (typename $filestat_t
@@ -552,8 +554,6 @@
 ;; The contents of a $subscription_t when type is `EVENTTYPE_CLOCK`.
 (typename $subscription_clock_t
   (struct
-    ;; The user-defined unique identifier of the clock.
-    (field $identifier $userdata_t)
     ;; The clock against which to compare the timestamp.
     (field $clock_id $clockid_t)
     ;; The absolute or relative timestamp.

phases/unstable/witx/wasi_unstable_preview0.witx → phases/snapshot/witx/wasi_snapshot_preview1.witx

@@ -8,7 +8,7 @@
 
 (use "typenames.witx")
 
-(module $wasi_unstable_preview0
+(module $wasi_snapshot_preview1
   ;; Linear memory to be accessed by WASI functions that need it.
   (import "memory" (memory))
 

tools/witx/tests/wasi_unstable.rs → tools/witx/tests/wasi.rs

@@ -2,31 +2,33 @@ use std::path::Path;
 use witx;
 
 #[test]
-fn validate_wasi_unstable_preview0() {
+fn validate_wasi_snapshot() {
     witx::load(Path::new(
-        "../../phases/unstable/witx/wasi_unstable_preview0.witx",
+        "../../phases/snapshot/witx/wasi_snapshot_preview1.witx",
     ))
     .unwrap_or_else(|e| panic!("failed to parse: {}", e));
 }
 
 #[test]
-fn validate_wasi_ephemeral_preview() {
+fn validate_wasi_ephemeral() {
     witx::load(Path::new(
         "../../phases/ephemeral/witx/wasi_ephemeral_preview.witx",
     ))
     .unwrap_or_else(|e| panic!("failed to parse: {}", e));
 }
 
 #[test]
-fn validate_wasi_old_preview0() {
-    witx::load(Path::new("../../phases/old/witx/wasi_unstable.witx"))
-        .unwrap_or_else(|e| panic!("failed to parse: {}", e));
+fn validate_wasi_old_snapshot_0() {
+    witx::load(Path::new(
+        "../../phases/old/snapshot_0/witx/wasi_unstable.witx",
+    ))
+    .unwrap_or_else(|e| panic!("failed to parse: {}", e));
 }
 
 #[test]
 fn render_roundtrip() {
     let doc = witx::load(Path::new(
-        "../../phases/unstable/witx/wasi_unstable_preview0.witx",
+        "../../phases/snapshot/witx/wasi_snapshot_preview1.witx",
     ))
     .unwrap_or_else(|e| panic!("failed to parse: {}", e));