diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index ad1997c..71aaf87 100644 --- a/.github/workflows/main.yml +++ b/.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 diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..4753095 --- /dev/null +++ b/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/ diff --git a/README.md b/README.md index 733036b..2217b28 100644 --- a/README.md +++ b/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 diff --git a/example-world.md b/example-world.md deleted file mode 100644 index c58d364..0000000 --- a/example-world.md +++ /dev/null @@ -1,72 +0,0 @@ -

World example-world

- -

Import interface example-dep-interface

-
-

Types

-

type example-dep-type

-

u32

-

-## Import interface example-interface -

Short interface description.

-

Explanation for developers using the interface API. It should include an -overview of the API as a whole as well as call out notable items in it, -for example example-api-type and example-api-function.

-
-

Types

-

type example-dep-type

-

example-dep-type

-

-#### `record example-api-type` -

Short type description

-

Explanation for developers using this type. It may be useful to give -some examples of places in the API where the type is used, such as in -the arguments and return type of example-api-function.

-
-Detailed specification -More rigorous specification details for implementers go here, if needed. -The intention is to keep the developer-oriented docs focused on things that -most developers will need to be aware of, while putting bulkier descriptions -of precise behavior here. -
-
Record Fields
- -
-

Functions

-

example-api-function: func

-

Short function description

-

Explanation for developers using the API. This should describe the -arguments which in this function are arg0, arg1, and arg2, and the -return value.

-
-Detailed specification -Similar to the details section above, this is meant for more rigorous -specification details for implementors. This may explain what a compliant -implementation MUST do, such as never returning an earlier result from a -later call, for example. -
-
Params
- -
Return values
- diff --git a/imports.md b/imports.md new file mode 100644 index 0000000..eac7ca4 --- /dev/null +++ b/imports.md @@ -0,0 +1,150 @@ +

World imports

+ +

Import interface wasi:i2c/i2c@0.2.0-draft

+

Inter-Integrated Circuit (I²C) API that is based upon hello-embedded and embedded-hal.

+
+

Types

+

type address

+

u16

+

An address value, in either 7-bit or 10-bit form, depending on the device. +

enum no-acknowledge-source

+

No-acknowledge error source.

+

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.

+
Enum Cases
+ +

variant error-code

+

Operation errors.

+
Variant Cases
+ +

variant operation

+

An operation used by the transaction method.

+
Variant Cases
+ +

resource i2c

+
+

Functions

+

[method]i2c.transaction: func

+

Execute the provided operations on the I²C bus.

+
Params
+ +
Return values
+ +

[method]i2c.read: func

+

Reads len bytes from address address.

+
Params
+ +
Return values
+ +

[method]i2c.write: func

+

Writes bytes to target with address address.

+
Params
+ +
Return values
+ +

[method]i2c.write-read: func

+

Writes bytes to address address and then reads read-len bytes +in a single transaction.

+
Params
+ +
Return values
+ +

Import interface wasi:i2c/delay@0.2.0-draft

+

Delays.

+
+

Types

+

resource delay

+

Delay with up to nanosecond precision.

+

Functions

+

[method]delay.delay-ns: func

+

Pauses execution for at minimum ns nanoseconds. Pause can be +longer if the implementation requires it due to precision/timing +issues.

+
Params
+ diff --git a/wit/delay.wit b/wit/delay.wit new file mode 100644 index 0000000..11d2794 --- /dev/null +++ b/wit/delay.wit @@ -0,0 +1,12 @@ +package wasi:i2c@0.2.0-draft; + +/// 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); + } +} diff --git a/wit/deps/example-dep/example-api.wit b/wit/deps/example-dep/example-api.wit deleted file mode 100644 index 60da323..0000000 --- a/wit/deps/example-dep/example-api.wit +++ /dev/null @@ -1,6 +0,0 @@ -// An example dependency, showing how these look. Actual proposals should -// delete this file and add their actual dependencies in the `deps` directory. - -interface example-dep-interface { - type example-dep-type = u32 -} diff --git a/wit/example.wit b/wit/example.wit deleted file mode 100644 index 04b0381..0000000 --- a/wit/example.wit +++ /dev/null @@ -1,59 +0,0 @@ -// Instructions for filling in this file: -// -// - Delete all these `//` comments, up to the first `///` comment. -// -// - Replace the remaining contents below with [Wit] code describing -// `interface`s and/or `world`s, using the same formatting style. -// -// If you want to include examples of the API in use, these should be in the -// README.md at the root of the repository and linked to from this file. -// -// [Wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md - -/// Short interface description. -/// -/// Explanation for developers using the interface API. It should include an -/// overview of the API as a whole as well as call out notable items in it, -/// for example `example-api-type` and `example-api-function`. -default interface example-interface { - use example-dep.example-api.example-dep-interface.{example-dep-type} - - /// Short type description - /// - /// Explanation for developers using this type. It may be useful to give - /// some examples of places in the API where the type is used, such as in - /// the arguments and return type of `example-api-function`. - /// - ///
- /// Detailed specification - /// More rigorous specification details for implementers go here, if needed. - /// The intention is to keep the developer-oriented docs focused on things that - /// most developers will need to be aware of, while putting bulkier descriptions - /// of precise behavior here. - ///
- record example-api-type { - /// A description of a field. - field0: u64, - /// A description of another field. - field1: string, - } - - /// Short function description - /// - /// Explanation for developers using the API. This should describe the - /// arguments which in this function are `arg0`, `arg1`, and `arg2`, and the - /// return value. - /// - ///
- /// Detailed specification - /// Similar to the details section above, this is meant for more rigorous - /// specification details for implementors. This may explain what a compliant - /// implementation MUST do, such as never returning an earlier result from a - /// later call, for example. - ///
- example-api-function: func( - arg0: example-api-type, - arg1: string, - arg2: example-dep-type, - ) -> result -} diff --git a/wit/i2c.wit b/wit/i2c.wit new file mode 100644 index 0000000..5875bf8 --- /dev/null +++ b/wit/i2c.wit @@ -0,0 +1,82 @@ +package wasi:i2c@0.2.0-draft; + +/// Inter-Integrated Circuit (I²C) API that is based upon [hello-embedded] and [embedded-hal]. +/// +/// [hello-embedded]: https://github.com/sunfishcode/hello-embedded/tree/main +/// [embedded-hal]: https://github.com/rust-embedded/embedded-hal +interface i2c { + /// An address value, in either 7-bit or 10-bit form, depending on the device. + type address = u16; + + /// Operation errors. + variant error-code { + /// 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. + bus, + + /// The arbitration was lost, e.g. electrical problems with the clock signal. + arbitration-loss, + + /// 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. + no-acknowledge(no-acknowledge-source), + + /// The peripheral receive buffer was overrun. + overrun, + + /// A different error occurred. + other, + } + + /// No-acknowledge error source. + /// + /// 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. + enum no-acknowledge-source { + /// The device did not acknowledge its address. The device may be + /// missing. + address, + + /// The device did not acknowledge the data. It may not be ready to + /// process requests at the moment. + data, + + /// Either the device did not acknowledge its address or the data, but + /// it is unknown which. + unknown, + } + + /// An operation used by the `transaction` method. + variant operation { + /// Read the give number of bytes. + read(u64), + + /// Write the given bytes. + write(list) + } + + resource i2c { + /// Execute the provided `operation`s on the I²C bus. + transaction: func( + address: address, + operations: list + ) -> result>, error-code>; + + /// Reads `len` bytes from address `address`. + read: func(address: address, len: u64) -> result, error-code>; + + /// Writes bytes to target with address `address`. + write: func(address: address, data: list) -> result<_, error-code>; + + /// Writes bytes to address `address` and then reads `read-len` bytes + /// in a single transaction. + write-read: func( + address: address, + write: list, + read-len: u64, + ) -> result, error-code>; + } +} diff --git a/wit/world.wit b/wit/world.wit index 17821ee..929ce7a 100644 --- a/wit/world.wit +++ b/wit/world.wit @@ -1,10 +1,6 @@ -// If the repository defines `interface`s, this file can define a minimal world -// which contains those interfaces, to allow documentation to be generated for -// them. -// -// Proposals should remove these `//` commments, and edit the `world` name and -// imports below to pull in their own `interface`s. +package wasi:i2c@0.2.0-draft; -default world example-world { - import example-interface: pkg.example.example-interface +world imports { + import i2c; + import delay; }