Suggested changes

.github/workflows/main.yml

@@ -10,7 +10,5 @@ jobs:
     name: Check ABI files are up-to-date
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
-    - uses: WebAssembly/wit-abi-up-to-date@v12
-      with:
-        wit-abi-tag: wit-abi-0.10.0
+    - uses: actions/checkout@v4
+    - uses: WebAssembly/wit-abi-up-to-date@v19

LICENSE.md

@@ -0,0 +1,8 @@
+Copyright © 2019-2023 the Contributors to the WASI Specification, published
+by the [WebAssembly Community Group][cg] under the
+[W3C Community Contributor License Agreement (CLA)][cla]. A human-readable
+[summary][summary] is available.
+
+[cg]: https://www.w3.org/community/webassembly/
+[cla]: https://www.w3.org/community/about/agreements/cla/
+[summary]: https://www.w3.org/community/about/agreements/cla-deed/

README.md

@@ -1,57 +1,34 @@
-# [Example WASI proposal]
-
-This template can be used to start a new proposal, which can then be proposed in the WASI Subgroup meetings.
-
-The sections below are recommended. However, every proposal is different, and the community can help you flesh out the proposal, so don't block on having something filled in for each one of them.
-
-Thank you to the W3C Privacy CG for the [inspiration](https://github.com/privacycg/template)!
-
-# [Title]
+# WASI I2C
 
 A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API.
 
 ### Current Phase
 
-[Fill in the current phase, e.g. Phase 1]
+wasi-i2c is currently in [Phase 1](https://github.com/WebAssembly/WASI/blob/main/Proposals.md#phase-1---feature-proposal-cg)
 
 ### Champions
 
-- [Champion 1]
-- [Champion 2]
-- [etc.]
-
-### Phase 4 Advancement Criteria
+- Friedrich Vandenberghe
+- Merlijn Sebrechts
+- Maximilian Seidler
 
-TODO before entering Phase 2.
+### Portability Criteria
 
-## Table of Contents [if the explainer is longer than one printed page]
-
-- [Introduction](#introduction)
-- [Goals [or Motivating Use Cases, or Scenarios]](#goals-or-motivating-use-cases-or-scenarios)
-- [Non-goals](#non-goals)
-- [API walk-through](#api-walk-through)
-  - [Use case 1](#use-case-1)
-  - [Use case 2](#use-case-2)
-- [Detailed design discussion](#detailed-design-discussion)
-  - [[Tricky design choice 1]](#tricky-design-choice-1)
-  - [[Tricky design choice 2]](#tricky-design-choice-2)
-- [Considered alternatives](#considered-alternatives)
-  - [[Alternative 1]](#alternative-1)
-  - [[Alternative 2]](#alternative-2)
-- [Stakeholder Interest & Feedback](#stakeholder-interest--feedback)
-- [References & acknowledgements](#references--acknowledgements)
+WASI-I2C must have at least two complete independent implementations. One implementation must be implemented on a microcontroller.
 
 ### Introduction
 
-[The "executive summary" or "abstract". Explain in a few sentences what the goals of the project are, and a brief overview of how the solution works. This should be no more than 1-2 paragraphs.]
+The WASI-I2C proposal defines an API for the I2C protocol. The API of [embedded_hal](https://github.com/rust-embedded/embedded-hal) is closely followed.
+
+Reference implementations can be found in [i2c-wasm-components](https://github.com/Zelzahn/i2c-wasm-components). Furthermore, there is also a [wasi-embedded-hal](https://crates.io/crates/wasi-embedded-hal) crate that implements the `embedded-hal` traits for the generated bindings.
 
-### Goals [or Motivating Use Cases, or Scenarios]
+### Goals
 
-[What is the end-user need which this project aims to address?]
+The primary goal is to provide an interface that WASI programs can use to read and write data over an I2C connection.
 
 ### Non-goals
 
-[If there are "adjacent" goals which may appear to be in scope but aren't, enumerate them here. This section may be fleshed out as your design progresses and you encounter necessary technical and other trade-offs.]
+Although I2C is in some aspects not that different from SPI, the purpose of this proposal is to solely focus on I2C.
 
 ### API walk-through
 
@@ -69,44 +46,19 @@ The full API documentation can be found [here](wasi-proposal-template.md).
 
 ### Detailed design discussion
 
-[This section should mostly refer to the .wit.md file that specifies the API. This section is for any discussion of the choices made in the API which don't make sense to document in the spec file itself.]
-
-#### [Tricky design choice #1]
-
-[Talk through the tradeoffs in coming to the specific design point you want to make.]
-
-```
-// Illustrated with example code.
-```
+#### Should this be combined with SPI, GPIO and PWM into 1 embedded proposal?
 
-[This may be an open question, in which case you should link to any active discussion threads.]
-
-#### [Tricky design choice 2]
-
-[etc.]
-
-### Considered alternatives
-
-[This section is not required if you already covered considered alternatives in the design discussion above.]
-
-#### [Alternative 1]
-
-[Describe an alternative which was considered, and why you decided against it.]
-
-#### [Alternative 2]
-
-[etc.]
+Although `embedded_hal` takes this approach, I would keep them separated for now. At least until each proposal is at least in Phase 2.
 
 ### Stakeholder Interest & Feedback
 
 TODO before entering Phase 3.
 
-[This should include a list of implementers who have expressed interest in implementing the proposal]
 
 ### References & acknowledgements
 
 Many thanks for valuable feedback and advice from:
 
-- [Person 1]
-- [Person 2]
-- [etc.]
+- Merlijn Sebrechts
+- Dan Gohman for the `hello-embedded` repository
+- Everyone else in SIG Embedded

imports.md

@@ -0,0 +1,150 @@
+<h1><a name="imports">World imports</a></h1>
+<ul>
+<li>Imports:
+<ul>
+<li>interface <a href="#wasi:i2c_i2c_0.2.0_draft"><code>wasi:i2c/[email protected]</code></a></li>
+<li>interface <a href="#wasi:i2c_delay_0.2.0_draft"><code>wasi:i2c/[email protected]</code></a></li>
+</ul>
+</li>
+</ul>
+<h2><a name="wasi:i2c_i2c_0.2.0_draft"></a>Import interface wasi:i2c/[email protected]</h2>
+<p>Inter-Integrated Circuit (I²C) API that is based upon <a href="https://github.com/sunfishcode/hello-embedded/tree/main">hello-embedded</a> and <a href="https://github.com/rust-embedded/embedded-hal">embedded-hal</a>.</p>
+<hr />
+<h3>Types</h3>
+<h4><a name="address"></a><code>type address</code></h4>
+<p><code>u16</code></p>
+<p>An address value, in either 7-bit or 10-bit form, depending on the device.
+<h4><a name="no_acknowledge_source"></a><code>enum no-acknowledge-source</code></h4>
+<p>No-acknowledge error source.</p>
+<p>In cases where it is possible, a device should indicate if a no
+acknowledge response was received to an address versus a no acknowledge
+to a data byte. Where it is not possible to differentiate, Unknown
+should be indicated.</p>
+<h5>Enum Cases</h5>
+<ul>
+<li>
+<p><a name="no_acknowledge_source.address"></a><a href="#address"><code>address</code></a></p>
+<p>The device did not acknowledge its address. The device may be
+missing.
+</li>
+<li>
+<p><a name="no_acknowledge_source.data"></a><code>data</code></p>
+<p>The device did not acknowledge the data. It may not be ready to
+process requests at the moment.
+</li>
+<li>
+<p><a name="no_acknowledge_source.unknown"></a><code>unknown</code></p>
+<p>Either the device did not acknowledge its address or the data, but
+it is unknown which.
+</li>
+</ul>
+<h4><a name="error_code"></a><code>variant error-code</code></h4>
+<p>Operation errors.</p>
+<h5>Variant Cases</h5>
+<ul>
+<li>
+<p><a name="error_code.bus"></a><code>bus</code></p>
+<p>Bus error occurred. e.g. A START or a STOP condition is detected and
+is not located after a multiple of 9 SCL clock pulses.
+</li>
+<li>
+<p><a name="error_code.arbitration_loss"></a><code>arbitration-loss</code></p>
+<p>The arbitration was lost, e.g. electrical problems with the clock signal.
+</li>
+<li>
+<p><a name="error_code.no_acknowledge"></a><code>no-acknowledge</code>: <a href="#no_acknowledge_source"><a href="#no_acknowledge_source"><code>no-acknowledge-source</code></a></a></p>
+<p>A bus operation was not acknowledged, e.g. due to the addressed
+device not being available on the bus or the device not being ready
+to process requests at the moment.
+</li>
+<li>
+<p><a name="error_code.overrun"></a><code>overrun</code></p>
+<p>The peripheral receive buffer was overrun.
+</li>
+<li>
+<p><a name="error_code.other"></a><code>other</code></p>
+<p>A different error occurred.
+</li>
+</ul>
+<h4><a name="operation"></a><code>variant operation</code></h4>
+<p>An operation used by the <code>transaction</code> method.</p>
+<h5>Variant Cases</h5>
+<ul>
+<li>
+<p><a name="operation.read"></a><code>read</code>: <code>u64</code></p>
+<p>Read the give number of bytes.
+</li>
+<li>
+<p><a name="operation.write"></a><code>write</code>: list&lt;<code>u8</code>&gt;</p>
+<p>Write the given bytes.
+</li>
+</ul>
+<h4><a name="i2c"></a><code>resource i2c</code></h4>
+<hr />
+<h3>Functions</h3>
+<h4><a name="method_i2c.transaction"></a><code>[method]i2c.transaction: func</code></h4>
+<p>Execute the provided <a href="#operation"><code>operation</code></a>s on the I²C bus.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="method_i2c.transaction.self"></a><code>self</code>: borrow&lt;<a href="#i2c"><a href="#i2c"><code>i2c</code></a></a>&gt;</li>
+<li><a name="method_i2c.transaction.address"></a><a href="#address"><code>address</code></a>: <a href="#address"><a href="#address"><code>address</code></a></a></li>
+<li><a name="method_i2c.transaction.operations"></a><code>operations</code>: list&lt;<a href="#operation"><a href="#operation"><code>operation</code></a></a>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="method_i2c.transaction.0"></a> result&lt;list&lt;list&lt;<code>u8</code>&gt;&gt;, <a href="#error_code"><a href="#error_code"><code>error-code</code></a></a>&gt;</li>
+</ul>
+<h4><a name="method_i2c.read"></a><code>[method]i2c.read: func</code></h4>
+<p>Reads <code>len</code> bytes from address <a href="#address"><code>address</code></a>.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="method_i2c.read.self"></a><code>self</code>: borrow&lt;<a href="#i2c"><a href="#i2c"><code>i2c</code></a></a>&gt;</li>
+<li><a name="method_i2c.read.address"></a><a href="#address"><code>address</code></a>: <a href="#address"><a href="#address"><code>address</code></a></a></li>
+<li><a name="method_i2c.read.len"></a><code>len</code>: <code>u64</code></li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="method_i2c.read.0"></a> result&lt;list&lt;<code>u8</code>&gt;, <a href="#error_code"><a href="#error_code"><code>error-code</code></a></a>&gt;</li>
+</ul>
+<h4><a name="method_i2c.write"></a><code>[method]i2c.write: func</code></h4>
+<p>Writes bytes to target with address <a href="#address"><code>address</code></a>.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="method_i2c.write.self"></a><code>self</code>: borrow&lt;<a href="#i2c"><a href="#i2c"><code>i2c</code></a></a>&gt;</li>
+<li><a name="method_i2c.write.address"></a><a href="#address"><code>address</code></a>: <a href="#address"><a href="#address"><code>address</code></a></a></li>
+<li><a name="method_i2c.write.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="method_i2c.write.0"></a> result&lt;_, <a href="#error_code"><a href="#error_code"><code>error-code</code></a></a>&gt;</li>
+</ul>
+<h4><a name="method_i2c.write_read"></a><code>[method]i2c.write-read: func</code></h4>
+<p>Writes bytes to address <a href="#address"><code>address</code></a> and then reads <code>read-len</code> bytes
+in a single transaction.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="method_i2c.write_read.self"></a><code>self</code>: borrow&lt;<a href="#i2c"><a href="#i2c"><code>i2c</code></a></a>&gt;</li>
+<li><a name="method_i2c.write_read.address"></a><a href="#address"><code>address</code></a>: <a href="#address"><a href="#address"><code>address</code></a></a></li>
+<li><a name="method_i2c.write_read.write"></a><code>write</code>: list&lt;<code>u8</code>&gt;</li>
+<li><a name="method_i2c.write_read.read_len"></a><code>read-len</code>: <code>u64</code></li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="method_i2c.write_read.0"></a> result&lt;list&lt;<code>u8</code>&gt;, <a href="#error_code"><a href="#error_code"><code>error-code</code></a></a>&gt;</li>
+</ul>
+<h2><a name="wasi:i2c_delay_0.2.0_draft"></a>Import interface wasi:i2c/[email protected]</h2>
+<p>Delays.</p>
+<hr />
+<h3>Types</h3>
+<h4><a name="delay"></a><code>resource delay</code></h4>
+<h2>Delay with up to nanosecond precision.</h2>
+<h3>Functions</h3>
+<h4><a name="method_delay.delay_ns"></a><code>[method]delay.delay-ns: func</code></h4>
+<p>Pauses execution for at minimum <code>ns</code> nanoseconds. Pause can be
+longer if the implementation requires it due to precision/timing
+issues.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="method_delay.delay_ns.self"></a><code>self</code>: borrow&lt;<a href="#delay"><a href="#delay"><code>delay</code></a></a>&gt;</li>
+<li><a name="method_delay.delay_ns.ns"></a><code>ns</code>: <code>u32</code></li>
+</ul>

wit/delay.wit

@@ -0,0 +1,12 @@
+package wasi:[email protected];
+
+/// Delays.
+interface delay {
+    /// Delay with up to nanosecond precision.
+    resource delay {
+        /// Pauses execution for at minimum `ns` nanoseconds. Pause can be
+        /// longer if the implementation requires it due to precision/timing
+        /// issues.
+        delay-ns: func(ns: u32);
+    }
+}