Merge pull request #3 from siwieme/main

WASI-USB Phase 2 Proposal

Author: merlijn-sebrechts

README.md

@@ -4,24 +4,40 @@ A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) A
 
 ### Current Phase
 
-WASI USB is currently in Phase 1.
+WASI USB is currently in Phase 2.
 
 ### Champions
 
 <!---
 Please limit to one champion per company or organization
 -->
 - Merlijn Sebrechts
-- Wouter Hennen
-- Warre Dujardin
+
+### Portability Criteria
+
+The API is designed to be portable across different platforms and environments, as it is based on the USB standard and Operating System APIs. The reference implementation can be used as a starting point for porting the API to different platforms. There will be provided at least two independent implementations in order to avoid baking in any libusb-specific behaviour.
+
+| Platform | Architecture | Reference Hardware |
+|----------|--------------|--------------------|
+| Windows  | x86_64       |                    |
+| Linux    | x86_64       |                    |
+| Linux    | aarch64      | Rasperry Pi 4      |
+| MacOS    | aarch64      | Macbook Pro M3 MAX |
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Goals](#goals)
+- [Non-goals](#non-goals)
+- [API walk-through](#api-walk-through)
+- [Considered alternatives](#considered-alternatives)
+- [References & acknowledgements](#references--acknowledgements)
 
 ### Introduction
 
 The WASI USB proposal adds an API for controlling USB devices. The API is meant to be used to with any kind of USB device, and is more low-level than, for example, accessing USb devices through the filesystem. The API design is based on the [libusb](https://libusb.info/) library, which is an often-used library for accessing USB devices in native programs. Just like libusb, this API aims to be a thin wrapper around the USB standard and Operating System APIs, with improved ergonomics where necessary. Access control can be applied to limit the devices a component can access.
 
-A reference implementation can be found [here](https://github.com/Wouter01/USB_WASI).
-
-### Goals [or Motivating Use Cases, or Scenarios]
+### Goals
 
 The goal of the proposal is to offer an API to control USB devices on a low level.
 
@@ -46,9 +62,12 @@ Being able to use the API in web browsers would be a nice thing to have, but aft
 
 ### References & acknowledgements
 
-Many thanks for valuable feedback and advice from:
+Many thanks for valuable feedback, work and advice from:
 
+- Michiel Van Kenhove
+- Friedrich Vandenberghe
 - Warre Dujardin
 - Wouter Hennen
+- Robbe Leroy
 
 This work has been partially supported by the ELASTIC project, which received funding from the Smart Networks and Services Joint Undertaking (SNS JU) under the European Union’s Horizon Europe research and innovation programme under Grant Agreement No 101139067. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union. Neither the European Union nor the granting authority can be held responsible for them. This funding supported individual contributor organisations, not the W3C or this community group as a whole.

wit/configuration.wit

@@ -0,0 +1,9 @@
+package component:usb@0.2.1;
+
+interface configuration {
+    /// ConfigValue is used to specify a configuration or an unconfigured state.
+    variant config-value {
+        unconfigured,      // Corresponds to -1 in libusb (unconfigure device)
+        value(u8)          // A valid configuration value (bConfigurationValue)
+    }
+}

wit/deps/example-dep/example-api.wit

@@ -0,0 +1,261 @@
+package wasi:cli@0.2.5;
+
+@since(version = 0.2.0)
+interface environment {
+  /// Get the POSIX-style environment variables.
+  ///
+  /// Each environment variable is provided as a pair of string variable names
+  /// and string value.
+  ///
+  /// Morally, these are a value import, but until value imports are available
+  /// in the component model, this import function should return the same
+  /// values each time it is called.
+  @since(version = 0.2.0)
+  get-environment: func() -> list<tuple<string, string>>;
+
+  /// Get the POSIX-style arguments to the program.
+  @since(version = 0.2.0)
+  get-arguments: func() -> list<string>;
+
+  /// Return a path that programs should use as their initial current working
+  /// directory, interpreting `.` as shorthand for this.
+  @since(version = 0.2.0)
+  initial-cwd: func() -> option<string>;
+}
+
+@since(version = 0.2.0)
+interface exit {
+  /// Exit the current instance and any linked instances.
+  @since(version = 0.2.0)
+  exit: func(status: result);
+
+  /// Exit the current instance and any linked instances, reporting the
+  /// specified status code to the host.
+  ///
+  /// The meaning of the code depends on the context, with 0 usually meaning
+  /// "success", and other values indicating various types of failure.
+  ///
+  /// This function does not return; the effect is analogous to a trap, but
+  /// without the connotation that something bad has happened.
+  @unstable(feature = cli-exit-with-code)
+  exit-with-code: func(status-code: u8);
+}
+
+@since(version = 0.2.0)
+interface run {
+  /// Run the program.
+  @since(version = 0.2.0)
+  run: func() -> result;
+}
+
+@since(version = 0.2.0)
+interface stdin {
+  @since(version = 0.2.0)
+  use wasi:io/streams@0.2.5.{input-stream};
+
+  @since(version = 0.2.0)
+  get-stdin: func() -> input-stream;
+}
+
+@since(version = 0.2.0)
+interface stdout {
+  @since(version = 0.2.0)
+  use wasi:io/streams@0.2.5.{output-stream};
+
+  @since(version = 0.2.0)
+  get-stdout: func() -> output-stream;
+}
+
+@since(version = 0.2.0)
+interface stderr {
+  @since(version = 0.2.0)
+  use wasi:io/streams@0.2.5.{output-stream};
+
+  @since(version = 0.2.0)
+  get-stderr: func() -> output-stream;
+}
+
+/// Terminal input.
+///
+/// In the future, this may include functions for disabling echoing,
+/// disabling input buffering so that keyboard events are sent through
+/// immediately, querying supported features, and so on.
+@since(version = 0.2.0)
+interface terminal-input {
+  /// The input side of a terminal.
+  @since(version = 0.2.0)
+  resource terminal-input;
+}
+
+/// Terminal output.
+///
+/// In the future, this may include functions for querying the terminal
+/// size, being notified of terminal size changes, querying supported
+/// features, and so on.
+@since(version = 0.2.0)
+interface terminal-output {
+  /// The output side of a terminal.
+  @since(version = 0.2.0)
+  resource terminal-output;
+}
+
+/// An interface providing an optional `terminal-input` for stdin as a
+/// link-time authority.
+@since(version = 0.2.0)
+interface terminal-stdin {
+  @since(version = 0.2.0)
+  use terminal-input.{terminal-input};
+
+  /// If stdin is connected to a terminal, return a `terminal-input` handle
+  /// allowing further interaction with it.
+  @since(version = 0.2.0)
+  get-terminal-stdin: func() -> option<terminal-input>;
+}
+
+/// An interface providing an optional `terminal-output` for stdout as a
+/// link-time authority.
+@since(version = 0.2.0)
+interface terminal-stdout {
+  @since(version = 0.2.0)
+  use terminal-output.{terminal-output};
+
+  /// If stdout is connected to a terminal, return a `terminal-output` handle
+  /// allowing further interaction with it.
+  @since(version = 0.2.0)
+  get-terminal-stdout: func() -> option<terminal-output>;
+}
+
+/// An interface providing an optional `terminal-output` for stderr as a
+/// link-time authority.
+@since(version = 0.2.0)
+interface terminal-stderr {
+  @since(version = 0.2.0)
+  use terminal-output.{terminal-output};
+
+  /// If stderr is connected to a terminal, return a `terminal-output` handle
+  /// allowing further interaction with it.
+  @since(version = 0.2.0)
+  get-terminal-stderr: func() -> option<terminal-output>;
+}
+
+@since(version = 0.2.0)
+world imports {
+  @since(version = 0.2.0)
+  import environment;
+  @since(version = 0.2.0)
+  import exit;
+  @since(version = 0.2.0)
+  import wasi:io/error@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:io/poll@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:io/streams@0.2.5;
+  @since(version = 0.2.0)
+  import stdin;
+  @since(version = 0.2.0)
+  import stdout;
+  @since(version = 0.2.0)
+  import stderr;
+  @since(version = 0.2.0)
+  import terminal-input;
+  @since(version = 0.2.0)
+  import terminal-output;
+  @since(version = 0.2.0)
+  import terminal-stdin;
+  @since(version = 0.2.0)
+  import terminal-stdout;
+  @since(version = 0.2.0)
+  import terminal-stderr;
+  @since(version = 0.2.0)
+  import wasi:clocks/monotonic-clock@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:clocks/wall-clock@0.2.5;
+  @unstable(feature = clocks-timezone)
+  import wasi:clocks/timezone@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:filesystem/types@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:filesystem/preopens@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/network@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/instance-network@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/udp@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/udp-create-socket@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/tcp@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/tcp-create-socket@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/ip-name-lookup@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:random/random@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:random/insecure@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:random/insecure-seed@0.2.5;
+}
+@since(version = 0.2.0)
+world command {
+  @since(version = 0.2.0)
+  import environment;
+  @since(version = 0.2.0)
+  import exit;
+  @since(version = 0.2.0)
+  import wasi:io/error@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:io/poll@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:io/streams@0.2.5;
+  @since(version = 0.2.0)
+  import stdin;
+  @since(version = 0.2.0)
+  import stdout;
+  @since(version = 0.2.0)
+  import stderr;
+  @since(version = 0.2.0)
+  import terminal-input;
+  @since(version = 0.2.0)
+  import terminal-output;
+  @since(version = 0.2.0)
+  import terminal-stdin;
+  @since(version = 0.2.0)
+  import terminal-stdout;
+  @since(version = 0.2.0)
+  import terminal-stderr;
+  @since(version = 0.2.0)
+  import wasi:clocks/monotonic-clock@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:clocks/wall-clock@0.2.5;
+  @unstable(feature = clocks-timezone)
+  import wasi:clocks/timezone@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:filesystem/types@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:filesystem/preopens@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/network@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/instance-network@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/udp@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/udp-create-socket@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/tcp@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/tcp-create-socket@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:sockets/ip-name-lookup@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:random/random@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:random/insecure@0.2.5;
+  @since(version = 0.2.0)
+  import wasi:random/insecure-seed@0.2.5;
+
+  @since(version = 0.2.0)
+  export run;
+}

wit/deps/wasi-cli-0.2.5/package.wit

@@ -0,0 +1,43 @@
+package wasi:clocks@0.2.5;
+
+interface monotonic-clock {
+  use wasi:io/poll@0.2.5.{pollable};
+
+  type instant = u64;
+
+  type duration = u64;
+
+  now: func() -> instant;
+
+  resolution: func() -> duration;
+
+  subscribe-instant: func(when: instant) -> pollable;
+
+  subscribe-duration: func(when: duration) -> pollable;
+}
+
+interface wall-clock {
+  record datetime {
+    seconds: u64,
+    nanoseconds: u32,
+  }
+
+  now: func() -> datetime;
+
+  resolution: func() -> datetime;
+}
+
+interface timezone {
+  use wall-clock.{datetime};
+
+  record timezone-display {
+    utc-offset: s32,
+    name: string,
+    in-daylight-saving-time: bool,
+  }
+
+  display: func(when: datetime) -> timezone-display;
+
+  utc-offset: func(when: datetime) -> s32;
+}
+