Contributing

First make sure you've got the tools installed per Getting Started.

Heads up that there are a lot of moving parts, and it's definitely not a simple process (sorry!). We hope that in future more of this will be generated / automated, but we're waiting for the WITX specification to stabilise before this is likely. If you have any ideas for simplifying the process please do let us know!

Proposing an API

So you recon we're missing a useful API? (you're probably right). Before going down the implementation path you may wish to open an issue for discussion.

Once you're ready to implement, there are a few steps to the process. You'll need to be familiar with building rust and C projects, if you run into any roadblocks please open an issue!

Adding the specification

  • Add a witx specification for the protocol to the specs

Updating the runtime (rust/wasmtime)

The rust runtime uses wiggle to automatically generate traits for binding. We provide an abstraction using these traits to hide the WASM implementation details, then implement these abstractions for viable platforms.

  • Update the list of specs in rt/src/api/mod.rs
  • Create a new API wrapper in rt/src/api/ to translate from wiggle generated traits to basic rust types, see rt/src/api/i2c_api.rs for an example
  • Add a mock implementation to rt/src/mock/ for mock execution, see rt/src/mock/i2c.rs for an example
  • Add a linux implementation to rt/src/linux/ for runtime use, see rt/src/linux/i2c.rs for an example

Because this is (currently) the only auto-generated component, we treat this runtime as the source-of-truth for testing other components.

To build/test the runtime you can run make runtime, or change into the rt directory and use cargo check or cargo watch -x check.

Updating the library (C/wasm3)

The wasme C library is designed to simplify porting and embedding. A simple Object Oriented C / VTable style object is provided for each API, hiding the internal wasm3 implementation from the user and supporting dependency injection and other useful testing tricks.

To add an API:

  • Create new source and header files in lib/src/ and lib/inc/wasme/
  • Add the new source file to lib/CMakeLists.txt to add it to the build
  • Add the new header file to lib/build.rs with appropriate allow-listing to support rust binding generation
  • Create C function declarations for the new methods and a container object (vtable-esque) to hold these
  • Add m3 calls for each new method, deferring to the container object
  • Add a helper function to bind an instance of this API to the wasme runtime (see WASME_bind_i2c).
  • Add C bindings to the rust runtime, see rt/src/wasm3/ for examples.

Explaining all of this is more difficult than showing so, see lib/src/i2c.c and lib/inc/wasme/i2c.h for an example.

When working with the library you can build with make lib, or use the classic CMake approach from lib/ of:

  • mkdir build && cd build to create and switch to a build directory
  • cmake .. to setup the project
  • make to perform a build

When the runtime is built with --features=wasm3 the ewasm library will also be included. You can use this instead however, the logs exposed when building under cargo leave a lot to be desired.

Updating the HAL (rust)

This HAL exposes the API to rust users, providing an implementation of embedded-hal.

  • Create a new source file in hal_rs/src/ for the new API
  • Create an API module with extern definitions for the WASI interface
  • Create a wrapper type for the API object, using the handle and extern functions, see hal_rs/src/i2c.rs for an example

Updating the HAL (AssemblyScript)

This HAL exposes the API to AssemblyScript users.

  • Create a new source file in hal_rs/src/ for the new API
  • Create an API module with extern definitions for the WASI interface
  • Create a wrapper type for the API object, using the handle and extern functions, see hal_rs/src/i2c.rs for an example

Updating the tests

Because there are many points at which the API specification / interpretation / execution can be incorrect, we run tests across both the runtime and library for every API.

  • Create an expectation file for the test in tests/, see tests/i2c.toml for an example
    • This should be named API.toml to work with existing makefiles
  • Create a test application in the Rust HAL to exercise the new API
    • Place the source in hal_rs/tests/
    • Add a [[bin]] section to hal_rs/Cargo.toml to build the test
    • This should be named test-API.rs to work with existing makefiles
  • Create a test application in the AssemblyScript HAL to exercise the new API

You can then build the tests with make tests which invokes a cargo build with the output in target/. Once the runtime has been updated (and built with make runtime) you can execute a test with make test-rt-API to execute this using the runtime (or make test-lib-API to use the runtime with wasm3 if supported).

Build and test commands

The project uses a top-level makefile to help simplify the collection of underlying commands.

Hints

  • All APIs use integer handles for each device/peripheral to avoid passing around opaque objects
    • On initialisation a positive handle should be returned
    • These handles are managed by the runtime and should be closed or will be cleaned-up on exit
  • Remember that the WASM runtime has it's own address space
    • Function calls with objects will resolve to an integer address that must be translated before access
    • If an object contains a pointer you will also need to translate this prior to accessing containing data
  • The WASM call ABI is not yet stable / widely supported
    • WITX allows multiple returns, in practice this may resolve to an extra argument in the function call (eg. fn do(a) -> Result<b, c> becomes fn do(a, &mut b) -> c in WASM)
  • The makefile re-maps a bunch of generated file paths to approximate using a workspace, this is helpful because workspaces do not support multiple targets