Zig wasm

[kassane]

New experiment.

Changes:

• Replaced clang-12 with zig toolchain v0.10 (llvm based 15.0.3);
• Experimented using zig-wasm (stage2/3 self-hosting)

cc: @urish

[kassane]

Note: Initial purpose for this contribution doesn't include adding embedded solutions written in zig like Microzig (similar embedded hal [rust]) or sample project like Zig on the Raspberry Pi Pico

[urish]

Very interesting!

What's the motivation behind switching clang-wasm to the zig toolchain?

[kassane]

Portability! The key for zig is having all the libc src:
https://github.com/ziglang/zig/tree/master/lib/libc

Including the zig toolchain might have a blob of his own in wasm.

• Nuke the C++ implementation of Zig from orbit using WASI ziglang/zig#13560

[urish]

Thanks! I'm not sure why portability is important here.

Can you please split the pull request into two:

• One with the clang-wasm changes
• One with the new zig-wasm builder

This will make it easier to test and discuss each one separately

[kassane]

@urish, done (splited)

[urish]

Thanks! So regarding zig-wasm, is there any way to move "wokwi_chip_ii.zig" into a different directory? Wokwi always clears the src directory before building the project.

[kassane]

Thanks! So regarding zig-wasm, is there any way to move "wokwi_chip_ii.zig" into a different directory? Wokwi always clears the src directory before building the project.

Done!

[urish]

Thanks! I'm doing some integration testing. Meanwhile, a few more things:

1. Why is the library file called wokwi_chip_ii? what does ii stand for?
2. I see that the pinMode function is missing (probably because we forgot to add it in the first version of the Rust API wrapper?)

[urish]

Ok, after some initial testing, I see that the .wasm file does not export the function table. Wokwi expects a function table to be exported as __indirect_function_table, otherwise, it can't invoke any of the user provided callback (such as pin_change). For example, in the Rust build, we achieve this using the --export-table linker argument.

Do you have any idea how to instruct zig to export the function table?

[urish]

One more thing I found:

4. Is it possible to automatically export a function called __wokwi_api_version_1 that always returns 1? Right now, Wokwi doesn't check it, but in the future, when we make changes to the chip API, Wokwi will use it to know which version of the API the compiled code is targeting. Here is how it's done in Rust.

[kassane]

One more thing I found:

4. Is it possible to automatically export a function called `__wokwi_api_version_1` that always returns 1? Right now, Wokwi doesn't check it, but in the future, when we make changes to the chip API, Wokwi will use it to know which version of the API the compiled code is targeting. [Here is](https://github.com/wokwi/wokwi_chip_ll/blob/2eb96d5abdce596dbd3114f84fd5b2e549bafc1c/src/lib.rs#L67-L74) how it's done in Rust.

Wow! cbindgen interpreted __wokwi_api_version_1 function as external instead of export.

---

verbose link

$> zig build --verbose-link
LLD Link... wasm-ld --error-limit=0 --stack-first --export=chipInit --export=__wokwi_api_version_1 -z stack-size=1048576 --no-entry --allow-undefined -o /home/kassane/Documentos/Projetos/wokwi-zb/zig-wasm/project/zig-cache/o/855a4f1f50c7af981e02026194e4268c/chip_zig.wasm /home/kassane/Documentos/Projetos/wokwi-zb/zig-wasm/project/zig-cache/o/855a4f1f50c7af981e02026194e4268c/chip_zig.wasm.o /home/kassane/.cache/zig/o/09929859fca6d3f6d14ba8e9662932fe/libc.a /home/kassane/.cache/zig/o/5e1af799a7414de202076d24c9667a2d/libcompiler_rt.a

[urish]

So can you please tell it to add --export-table to the wasm-ld options?

[kassane]

So can you please tell it to add --export-table to the wasm-ld options?

zig build --verbose-link
LLD Link... wasm-ld --error-limit=0 --stack-first --export=table -z stack-size=1048576 --no-entry --allow-undefined -o /home/kassane/Documentos/Projetos/wokwi-zb/zig-wasm/project/zig-cache/o/855a4f1f50c7af981e02026194e4268c/chip_zig.wasm /home/kassane/Documentos/Projetos/wokwi-zb/zig-wasm/project/zig-cache/o/855a4f1f50c7af981e02026194e4268c/chip_zig.wasm.o /home/kassane/.cache/zig/o/09929859fca6d3f6d14ba8e9662932fe/libc.a /home/kassane/.cache/zig/o/5e1af799a7414de202076d24c9667a2d/libcompiler_rt.a

Reference:

• wasm output contains compiler_rt exports ziglang/zig#2910 (comment)

[kassane]

1. Why is the library file called wokwi_chip_ii? what does ii stand for?

I just copied the name from the original library. Do you want me to rename it?

[urish]

The last change added --export=table and not --export-table, which results in an empty wasm binary:

(module
  (table $table0 1 1 funcref)
  (memory $memory (;0;) (export "memory") 16)
  (global $global0 (mut i32) (i32.const 1048576))
)

I just copied the name from the original library. Do you want me to rename it?

The original name ended with ll, which stands for low-level. For Rust, we intend to create an higher level API abstraction in the future (probably called wokwi_chip_hal or similar), so most users won't actually use the wokwi_chip_ll directly.

[kassane]

@urish , done

zig build --verbose-link
LLD Link... wasm-ld --error-limit=0 --export-table --stack-first --export=chipInit --export=__wokwi_api_version_1 -z stack-size=1048576 --no-entry --allow-undefined -o /home/kassane/Documentos/Projetos/wokwi-zb/zig-wasm/project/zig-cache/o/855a4f1f50c7af981e02026194e4268c/chip_zig.wasm /home/kassane/Documentos/Projetos/wokwi-zb/zig-wasm/project/zig-cache/o/855a4f1f50c7af981e02026194e4268c/chip_zig.wasm.o /home/kassane/.cache/zig/o/09929859fca6d3f6d14ba8e9662932fe/libc.a /home/kassane/.cache/zig/o/5e1af799a7414de202076d24c9667a2d/libcompiler_rt.a

[urish]

Thanks, I'll test it shortly!

By the way, how did you find out about Wokwi? What was the motivation for adding zig support for the custom chips?

[kassane]

Thanks, I'll test it shortly!

By the way, how did you find out about Wokwi?

I got to know wokwi through the franzininho community.

What was the motivation for adding zig support for the custom chips?

Earlier I spoke only about portability, though believe that zig can improve on this by making solutions simpler (Low Level) and more lightweight.
I don't consider it a competitor to rust because it is inspired by rust, but with a C profile.

[urish]

Thanks! I did some initial testing, and it seems to work well. I'll merge and deploy the builder to the staging environment, so you can play around and provide feedback too.

From my testing so far, Zig seems very efficient at producing small wasm binaries!

[urish]

p.s. good job on creating a tidy container. Usually pull requests require a lot more effort and feedback from my end to get them working well and be easy to maintain in the future. For most pull requests this takes weeks - you did it in under 3 hours!

[urish]

Link to a demo project in the staging environment: https://zig.preview.wokwi.com/projects/348776765607379539

I'd love if you created a few more custom chips to test the integration with the new builder. If you need some ideas, there are several examples here: https://link.wokwi.com/custom-chips-alpha (under the Chip examples section)

[kassane]

Hi @urish

It will be a pleasure to help in my spare time and I have even been doing some documentation testing of the zig wrapper.

doc src [sample]: zig-doc_wokwi_API.tar.gz

Preview:

How to generate doc?

Single-file

$> zig build-{lib,exe,obj} mylib.zig -femit-docs

Project

• open build.zig
• add lib.emit_docs = .{ .emit_to = "custom/path" }; or lib.emit_docs = .emit;

Reference

• Zig Documentation - doc comments

[urish]

Thanks! As far as I understand it, Zig does not have a standard library manager yet, so the only way to have documentation is to self-host it?

[kassane]

Exactly.