From 5753dd330b5ca598d590bd08b572759029f4a9bf Mon Sep 17 00:00:00 2001 From: Zelzahn Date: Sat, 9 Mar 2024 22:34:05 +0100 Subject: [PATCH 1/4] add interface --- .github/workflows/main.yml | 6 +- LICENSE.md | 8 +++ README.md | 78 +++++--------------------- example-world.md => imports.md | 10 ++-- wit/delay.wit | 12 ++++ wit/deps/example-dep/example-api.wit | 6 -- wit/example.wit | 59 -------------------- wit/i2c.wit | 82 ++++++++++++++++++++++++++++ wit/world.wit | 12 ++-- 9 files changed, 127 insertions(+), 146 deletions(-) create mode 100644 LICENSE.md rename example-world.md => imports.md (83%) create mode 100644 wit/delay.wit delete mode 100644 wit/deps/example-dep/example-api.wit delete mode 100644 wit/example.wit create mode 100644 wit/i2c.wit diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index ad1997c..b944a0d 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@v17 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..60c5e43 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,32 @@ -# [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.] +- Friedrich Vandenberghe +- Merlijn Sebrechts +- Maximilian Seidler ### Phase 4 Advancement Criteria TODO before entering Phase 2. -## 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) - ### 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. -### 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 +44,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. -``` - -[This may be an open question, in which case you should link to any active discussion threads.] +#### Should this be combined with SPI, GPIO and PWM into 1 embedded proposal? -#### [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.] +I'm not sure, although `embedded_hal` takes this approach it seems to me that until enough stakeholders are found the scope is best kept contained. ### 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/imports.md similarity index 83% rename from example-world.md rename to imports.md index c58d364..8c60710 100644 --- a/example-world.md +++ b/imports.md @@ -1,19 +1,19 @@ -

World example-world

+

World imports

-

Import interface example-dep-interface

+

Import interface wasi:example-api-package/example-dep-interface

Types

type example-dep-type

u32

-## Import interface example-interface +## Import interface wasi:example-package/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, diff --git a/wit/delay.wit b/wit/delay.wit new file mode 100644 index 0000000..dc12cfc --- /dev/null +++ b/wit/delay.wit @@ -0,0 +1,12 @@ +package wasi:i2c@0.0.0; + +/// 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); + } +} \ No newline at end of file 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..f065a87 --- /dev/null +++ b/wit/i2c.wit @@ -0,0 +1,82 @@ +package wasi:i2c@0.0.0; + +/// 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..ee7b76b 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.0.0; -default world example-world { - import example-interface: pkg.example.example-interface +world imports { + import i2c; + import delay; } From da841dd4e51b9f9ef36a1ad433608dfb2e5eb94f Mon Sep 17 00:00:00 2001 From: Zelzahn Date: Sun, 17 Mar 2024 14:04:48 +0100 Subject: [PATCH 2/4] add links to implementations --- README.md | 4 +++- wit/delay.wit | 2 +- wit/i2c.wit | 2 +- wit/world.wit | 2 +- 4 files changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 60c5e43..33d5dd5 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,8 @@ TODO before entering Phase 2. 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 The primary goal is to provide an interface that WASI programs can use to read and write data over an I2C connection. @@ -46,7 +48,7 @@ The full API documentation can be found [here](wasi-proposal-template.md). #### Should this be combined with SPI, GPIO and PWM into 1 embedded proposal? -I'm not sure, although `embedded_hal` takes this approach it seems to me that until enough stakeholders are found the scope is best kept contained. +Although `embedded_hal` takes this approach, I would keep them seperated for the time being. At least until each proposal is at least in Phase 2. ### Stakeholder Interest & Feedback diff --git a/wit/delay.wit b/wit/delay.wit index dc12cfc..e29fc1d 100644 --- a/wit/delay.wit +++ b/wit/delay.wit @@ -1,4 +1,4 @@ -package wasi:i2c@0.0.0; +package wasi:i2c@0.1.0; /// Delays. interface delay { diff --git a/wit/i2c.wit b/wit/i2c.wit index f065a87..217e1b1 100644 --- a/wit/i2c.wit +++ b/wit/i2c.wit @@ -1,4 +1,4 @@ -package wasi:i2c@0.0.0; +package wasi:i2c@0.1.0; /// Inter-Integrated Circuit (I²C) API that is based upon [hello-embedded] and [embedded-hal]. /// diff --git a/wit/world.wit b/wit/world.wit index ee7b76b..9f0f99a 100644 --- a/wit/world.wit +++ b/wit/world.wit @@ -1,4 +1,4 @@ -package wasi:i2c@0.0.0; +package wasi:i2c@0.1.0; world imports { import i2c; From dc365f93fbbf760163144cd42d6b285542116e08 Mon Sep 17 00:00:00 2001 From: Zelzahn Date: Mon, 18 Mar 2024 17:50:58 +0100 Subject: [PATCH 3/4] add portability criteria --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 33d5dd5..2217b28 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,9 @@ wasi-i2c is currently in [Phase 1](https://github.com/WebAssembly/WASI/blob/main - Merlijn Sebrechts - Maximilian Seidler -### Phase 4 Advancement Criteria +### Portability Criteria -TODO before entering Phase 2. +WASI-I2C must have at least two complete independent implementations. One implementation must be implemented on a microcontroller. ### Introduction @@ -48,7 +48,7 @@ The full API documentation can be found [here](wasi-proposal-template.md). #### Should this be combined with SPI, GPIO and PWM into 1 embedded proposal? -Although `embedded_hal` takes this approach, I would keep them seperated for the time being. At least until each proposal is at least in Phase 2. +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 From b88f92cb970688878ee3475c3416e3e49f5d37ad Mon Sep 17 00:00:00 2001 From: Zelzahn Date: Tue, 19 Mar 2024 08:32:37 +0100 Subject: [PATCH 4/4] apply sugessted changes --- .github/workflows/main.yml | 2 +- imports.md | 176 ++++++++++++++++++++++++++----------- wit/delay.wit | 4 +- wit/i2c.wit | 2 +- wit/world.wit | 2 +- 5 files changed, 132 insertions(+), 54 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index b944a0d..71aaf87 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -11,4 +11,4 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - uses: WebAssembly/wit-abi-up-to-date@v17 + - uses: WebAssembly/wit-abi-up-to-date@v19 diff --git a/imports.md b/imports.md index 8c60710..eac7ca4 100644 --- a/imports.md +++ b/imports.md @@ -2,71 +2,149 @@ -

Import interface wasi:example-api-package/example-dep-interface

+

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 example-dep-type

-

u32

-

-## Import interface wasi:example-package/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
+

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
  • -

    field0: u64

    -

    A description of a field. +

    address

    +

    The device did not acknowledge its address. The device may be +missing. +

    • +
  • +

    data

    +

    The device did not acknowledge the data. It may not be ready to +process requests at the moment.

  • -

    field1: string

    -

    A description of another field. +

    unknown

    +

    Either the device did not acknowledge its address or the data, but +it is unknown which.

+

variant error-code

+

Operation errors.

+
Variant Cases
+
    +
  • +

    bus

    +

    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. +

    • +
  • +

    arbitration-loss

    +

    The arbitration was lost, e.g. electrical problems with the clock signal. +

    • +
  • +

    no-acknowledge: no-acknowledge-source

    +

    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. +

    • +
  • +

    overrun

    +

    The peripheral receive buffer was overrun. +

    • +
  • +

    other

    +

    A different error occurred. +

    • +
+

variant operation

+

An operation used by the transaction method.

+
Variant Cases
+
    +
  • +

    read: u64

    +

    Read the give number of bytes. +

    • +
  • +

    write: list<u8>

    +

    Write the given bytes. +

    • +
+

resource i2c

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. -
+

[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
+
    +
  • self: borrow<delay>
    • +
  • ns: u32
diff --git a/wit/delay.wit b/wit/delay.wit index e29fc1d..11d2794 100644 --- a/wit/delay.wit +++ b/wit/delay.wit @@ -1,4 +1,4 @@ -package wasi:i2c@0.1.0; +package wasi:i2c@0.2.0-draft; /// Delays. interface delay { @@ -9,4 +9,4 @@ interface delay { /// issues. delay-ns: func(ns: u32); } -} \ No newline at end of file +} diff --git a/wit/i2c.wit b/wit/i2c.wit index 217e1b1..5875bf8 100644 --- a/wit/i2c.wit +++ b/wit/i2c.wit @@ -1,4 +1,4 @@ -package wasi:i2c@0.1.0; +package wasi:i2c@0.2.0-draft; /// Inter-Integrated Circuit (I²C) API that is based upon [hello-embedded] and [embedded-hal]. /// diff --git a/wit/world.wit b/wit/world.wit index 9f0f99a..929ce7a 100644 --- a/wit/world.wit +++ b/wit/world.wit @@ -1,4 +1,4 @@ -package wasi:i2c@0.1.0; +package wasi:i2c@0.2.0-draft; world imports { import i2c;