Feature Request: Module Preprocessing for Resource-Constrained Targets

[FedorSmirnov89]

Overview

I'm requesting a feature to add module preparsing capabilities to Wasmi, enabling the creation of lightweight builds that can run on resource-constrained embedded systems without requiring the full parsing and validation overhead.

Use Case

I'm working on deploying Wasmi on an nRF53 (Nordic's dual-core Cortex-M33 chip) alongside Embassy async runtime and the BLE stack. The target system has approximately 1MB of total memory, and the current Wasmi implementation consumes around 480 KiB when combined with Embassy.

With a proof-of-concept implementation of the proposed preprocessing feature (see #1636 ), this footprint can be reduced to approximately 250 KiB - roughly a 48% reduction in memory usage.

Proposed Solution

The feature would add module serialization and deserialization capabilities to Wasmi, allowing:

1. Preprocessing Phase: Parse and validate WebAssembly modules on a development machine or build server
2. Serialization: Convert the parsed module to a compact, platform-independent binary format
3. Lightweight Runtime: Deploy only the deserialization-capable Wasmi build to the target device
4. Runtime Loading: Load preprocessed modules directly without parsing overhead

Benefits

• Memory Efficiency: Significant reduction in runtime memory footprint, making it possible to run wasmi on smaller devices
• Cross-Platform: Serialized modules can be created on one (resource-rich) platform and deployed on another, more constrained platform
• Feature-Gated: Can be enabled only when needed, maintaining Wasmi's modular architecture

Implementation Approach

I propose implementing this as a feature-gated part of the main Wasmi crate, providing:

• serialization feature for creating serialized modules
• deserialization feature for lightweight runtime builds
• parser feature which is a default feature. By excluding this feature, we can create a wasmi build without the parsing/validation/translation machinery
• Integration with Wasmi's existing module system

Current Status

I have implemented a proof-of-concept version that demonstrates the concept and provides concrete performance measurements (#1636 ). The implementation includes:

• Module serialization/deserialization using Postcard format
• Comprehensive test coverage
• Error handling for various failure modes
• Feature-gated compilation

Next Steps

I would be happy to work with the Wasmi maintainers to implement this feature properly, starting from scratch if needed. The current implementation is primarily intended to demonstrate the concept and gather feedback on the approach.

Example Implementation

I've created an example repository demonstrating the usage and performance benefits of this feature: Preparsing Example. The repository shows:

• How to use the serialization/deserialization APIs
• Memory footprint measurements
• Integration with embedded Rust applications

Questions for Discussion

1. Does this approach align with Wasmi's architecture and design goals?
2. Are there concerns about maintaining backward compatibility?
3. What level of feature completeness should be targeted for the initial implementation?
4. How should this integrate with Wasmi's existing feature flags and compilation modes?

I'm open to feedback and willing to adjust the approach based on maintainer guidance and community input. Thank you :)

[Robbepop]

Hi @FedorSmirnov89!

The reason why we have not implemented Wasm module (de)serialization in Wasmi, (yet), is that Wasmi's translation is already extremely fast if you use the correct settings. So let me ask you first:

• Have you used CompilationMode::Lazy?
• Have you used Module::new_unchecked?

Combined the reduce startup times by up to 100x in some cases making Wasm module (de)serialization practically irrelevant.
Furthermore, Wasmi is extremely dependent on proper optimization settings, so please make sure that you compile Wasmi with

[profile.release]
lto = "fat"
codegen-units = 1

Now I am not sure what you meant with memory footprint that has been reduced in your PR from 480KiB to 250KiB. Is this the Wasmi binary size? The serialized Wasm modules? The memory footprint during Wasmi execution? Could you please elaborate?

Thanks!

[Robbepop]

@FedorSmirnov89 I have taken a quick look at your example Wasmi usage at:
https://github.com/FedorSmirnov89/preparsed-example/blob/main/shared/src/lib.rs

Some recommendations:

1. Never use opt-level="z". I know there are still a lot of recommendations to do just that, however, in practice opt-level="s" produces similarly small code while retaining most of the performance compared to opt-level=3. And sometimes opt-level=3 actually produces smaller binaries. Always test and verifiy.
2. An obvious one: please update to the newest Wasmi v0.51.0 as it should compile to more efficient code compared to Wasmi v0.47.0 that you are currently using.
3. Use Config::compilation_mode(CompilationMode::Lazy) to lazily compile Wasm modules. This way, especially big .wasm binaries have a ~30x improved startup time.
4. Use Module::new_unchecked if you ensured that your .wasm binaries are valid. No need to re-validate them all the time. I am not sure about this, but maybe Rust\LLVM's optimizer or the linker can actually optimize away all the unused wasmparser validation infrastructure. In case it won't we may be able to add a validate crate feature to the wasmi crate in order to not compile all the validation infrastructure in the first place if not needed.
5. Avoiding using the wasmi::Linker to instantiate Wasm modules. The wasmi::Linker can be seen as a convenience type but it isn't really efficient, especially not if you care about binary sizes. Prefer to use Instance::new and provide it with a buffer of externals that you can create yourself statically via matching on the Wasm module's imports. You can query a Wasm modules imports via Module::imports.
6. Do not use anyhow as this might pull in Rust's entire formatting infrastructure which is HUGE. If you want to error, then simply panic without a message or a short &'static str message and always avoid using format!, println! or anything similar.

[FedorSmirnov89]

Hi @Robbepop :)

Thanks a lot for you quick response.

You are right, I should have started by describing our use case: We are looking into the usage of Wasm on resource-restricted targets (such as the nrf53 I am using for testing). The idea is that using Wasm will provide more flexibility, since we can change the behavior of an embedded node by loading a new Wasm module (e.g., per bluetooth), instead of having to reflash the device. The other benefit is that with Wasm, you significantly lower the possibility of "bricking" you device: Even if the Wasm module you load has errors or is misconfigured for the target, this will only result in a host trap and you can still (remotely) load an updated/fixed version of the module (instead of your firmware panicking and dying).

Now, with these resource-restricted devices in mind, our main bottleneck is the amount of available flash- and RAM memory. Performance in the sense of execution latency of the module functionality is not a factor at all at this point, we are just trying to fit everything we need (a Wasm runtime, Embassy, the BLE communication primitives, and the implementation of the host functions) onto the target.

So, when I talk about the "memory footprint", I am referring to the amount of flash memory required on an nrf53 if flashed with a minimal firmware containing (a) an example Wasm module, (b) a Wasm runtime (wasmi or tinywasm), and (c) embassy.

From this perspective, the serialization/deserialization feature I am talking about in this issue has the main benefit of enabling us to put fewer parts of wasmi onto the resource-restricted target: Serializing wasmi's IR on a build node enables us to load only a stripped version - which does not contain any of the logic for parsing wasm code - onto the resource-restricted target. In the initial tests I have been doing with the wasmi version from the draft branch #1636 , the amount of required flash is reduced by roughly 50%.

So, to summarize: The main benefit of the proposed feature from my perspective would be the reduction of the firmware/binary sized when deploying wasmi with only the "deserialization" feature.

What do you think?

[FedorSmirnov89]

@Robbepop : Thanks a lot for reviewing the examples and for your recommendations. I have tried all of them out and pushed an updated version of the example repo. In detail:

1. Opt-levels: "z" versus "s" : I tried switching between "z" and "s". The initial take-away is that "z" does result in smaller binaries, but not by much. I still have to test it on the actual nrf53 and see how it affects the firmware size
2. Updating the Wasmi version: I rebased the (Proof-of-Concept/Draft) Pre-parsing feature #1636 onto the current master and updated the example dependencies. So they should be using the up-to-date version of wasmi now.
3. Hmmm... In our use case, the startup time and generally the execution latency is, at least at the moment, a much lower priority than the size of the binary/firmware. I may be misunderstanding, but wouldn't the usage of lazy compilation mean that we always need the translation machinery on the target, since it may become necessary to compile functions at runtime? My idea was that, for the smallest targets, the compilation would always be eager to do as much work as possible on a more powerful build node and place as little parsing and translation logic on the target node as possible. Does that make sense?
4. Thank you for the tip with new_unchecked. It actually reduces the size considerably. What are the implications of it being unsafe? Will the method panic if the the module is actually invalid? Is it possible to get panics at runtime?
5. Thank you for the tip with the linker. I have re-implemented the way that the host functions are linked. That did not seem to change the binary size. Still have to test this with the actual target.
6. Ah ya, of course. The usage of anyhow is just something I quickly did for the example repo. At the target, we are using defmt with static strings. In production, we could switch to using just error codes.

Thank you again for your recommendations. I am new to wasmi, so they are extremely helpful 👍🏻

[Robbepop]

@FedorSmirnov89

1. Even if opt-level="z" produces marginally smaller binaries you should really use opt-level="s" with Wasmi. The reason is that Wasmi's performance regresses by up to 200% compared to opt-level=3 with opt-level="z" whereas it only regresses by ~25% when using opt-level="s".
2. For the future, I'd appreciate you not force pushing because that makes reviewing way harder. It is still in draft so it is okay but once you want it to be reviewed, pls refrain from overwriting its PR history with forced pushes.
3. Yes, then maybe lazy compilation isn't a solution for your current problem. However, you should keep this in the back of your head once you run into startup bottlenecks.
4. Can you shed light on how much Module::new_unchecked improve binary sizes for you? (percentage) Docs can be found here: https://docs.rs/wasmi/latest/wasmi/struct.Module.html#method.new_unchecked It is basically undefined behavior if you pass it invalid Wasm binaries. It is your responsibility to pre-validate the inputs. If you have full control over the Wasm binaries you are inputting (which I guess you do since with (de)serialized modules you run into the absolute same issues).
5. Can you show me the new code using Instance::new? I would really wonder if it wouldn't improve performance and especially binary size by quite a bit if done correctly.
6. Okay, glad to hear that.

---

So maybe if the tests with Module::new_unchecked were successful we could experiment with going one step further by adding the aforementioned validate crate feature to really get rid of anything that does Wasm validation. Thankfully the wasmparser crate already has such a validate crate feature which could be turned off by wasmi via some update. Not sure how much work this is going to be.

---

Okay thank you for detailing me about your precise use case. It sound interesting indeed and could be a fit for Wasmi.

First of all, I am impressed that you managed to implement (de)serialization in Wasmi and it is (supposedly?) working. That is because Wasmi was never intended (for aforementioned reasons) to do any of that and was thus also not architected to support this feature. To recap: Wasmi's parsing, validation and translation schemes are intended to be so simple, efficient and fast as to not require (de)serialization to begin with, especially with lazy and unchecked translation.

Technically, those serialized Wasmi modules are some form of a cache that adds a ton of maintenance and tech-debt since we can never really change its format without breaking user code and their serialized modules. So, from a technical standpoint having such a feature is a huuuuuge tech-debt that a project takes which is also a reason why I never intended to add this to Wasmi and instead try to find ways to make it unnecessary in the first place.

Furthermore, deserialization of those Wasmi modules also need parsing and validation; OR you run into the same undefined behavior issues as with unchecked module translation that anything can happen if you input an invalid serialized Wasmi module. Therefore, this is also display a potentially huge security issue.

Finally, I had plans for Wasmi's future development that further improves Wasmi's execution performance that would anihilate the ability to do Wasmi module serialization at all as a trade-off (unfortunately). Maybe one could do Wasmi instance serialization instead then but this already goes into too much details. The point is: if we merged such functionality into Wasmi, we could never go back and do what is currently on the roadmap for Wasmi.

Having said all that, I still find it very valuable to explore this feature further and would like to encourage you to do so. However, if another solution (e.g. validate crate feature) would strike a similar (or almost similar) binary size win, it would arguably be the simpler and thus preferred solution.

[Robbepop]

@FedorSmirnov89 concerning more control over memory consumption: Module::new_streaming (used correctly) might be useful for you: #1515 (comment)

[FedorSmirnov89]

Hi @Robbepop 👋

Thanks again for taking the time to walk me through all these details. I totally get your concerns about the tech debt that a serialization approach would introduce. When I put together the draft PR, I also had the feeling that I was forcing a lot of module internals into the open just to make the serialization work, so your point makes perfect sense.

I also really appreciate the guidance you’ve been giving me on how to properly configure Wasmi to get the binary size down. I tried to apply all of your recommendations in the example repo, including a version that uses Instance::new instead of the Linker. It would be great if you could have a quick look at that implementation (in this file) and let me know if I did it the right way, or if there’s still something obvious I could improve.

One thought I had: would you be open to adding an example in Wasmi that explicitly shows how to configure and use it in a way that results in the smallest possible binary for an embedded target? Something that pulls together all of these best practices in one place—opt-level = "s", lto = "fat", Instance::new, Module::new_unchecked, etc. Such an example could serve as a reference for anyone trying to get Wasmi onto resource-constrained devices, and it would also provide a consistent way to measure the effect of changes (e.g., how much new_unchecked helps, or how this compares to the binary size you can get with the serialization prototype).

What do you think—would this be something that fits into Wasmi’s examples? I would be happy to make a PR with such an example.

[Robbepop]

@FedorSmirnov89 you are welcome: FedorSmirnov89/preparsed-example#1

I also thought about writing some docs for embedded users. Haven't thought about setting up a whole Wasmi example as I haven't got any examples (so far) in the wasmi repository. Maybe we should have some. I kinda like doc tests a bit more, but that's just a personal and maybe bad preference.

Can you tell me how much the new link_externals improved the situation for you?
Are you still in need of the Wasmi module (de)serialization with all the tricks (e.g. also Module::new_streaming) applied?

I'd certainly welcome help with docs or examples if you are willing to invest time and effort. :)

[FedorSmirnov89]

Hmmm. I've tried several setups to have something which is easy to setup and run and which at the same time gives a good approximation of the binary size that a minimum example would have on an nrf53. Unfortunately, I didn't get it to work: Without real linking, it seemed to always optimize out the code. So I unfortunately don't know a way to set up something that could provide realistic binary size estimations other than an actual project which would be compiled for a real target - this, of course would not work for an example integrated in the wasmi repository.

I did some testing with such a project though (running a minimal module similar to the one in the example repo I shared, but actually accessing the peripherals of an nrf53 dev board). There, I had a look at the size of the firmware that is being flashed onto the target with different ways of running the wasmi code.

For the numbers below, note that they don't just measure the size contribution of wasmi: We also have embassy on the board (same code for all deployment options) and we statically load the Wasm module into the flash memory (the bytes of the .wasm file in the normal case and the serialized module in case of the serialization feature). The firmware uses static strings for error handling.

With that, the size of the firmware is as follows:

Mode	Module size	Firmware size
No tricks (Linker + Module::new)	7 KiB	472 KiB
No linker	7 KiB	464 KiB
No linker + new_unchecked	7 KiB	464 KiB
Deserializing module (based on the prototype branch)	5.3 KiB	252 KiB

I don't know why using new_unchecked did not have any effect here. It seemed to make a larger difference for the size of the binary I used in the example repo.

Note that I compiled all modes with the compilation mode z . Compiling it with s results in a larger firmware. For instance, the firmware for the No linker + new_unchecked mode has a size of 604 KiB when compiled with s (which is a substantial increase on that scale).

Regarding the question whether we still would require the Wasmi deserialization:

To be honest, it is hard to say. We are currently doing our initial development for the nrf53, which we expect to be our smallest/most resource-restricted target. Now, on the one hand, it has 1 MB of flash (which is why I can test all the modes in the first place). However, we require other things on it, such as the primitives for BLE communication and likely substantially more host functions. We, therefore, don't really have a fix number that we want to get and are more in the "smaller is better" state. We also evaluated the usage of tinywasm. When using its serialization option, a firmware similar to what I used for the tests above requires around 140 KiB. So we likely will, at least initially use tinywasm to have as much memory as possible available for future-proofing.

On the other hand, wasmi's requirements are totally fine for the larger embedded targets that we will look at next and I really like many of its features (fuel metering in particular; an option of running the module asynchronously, similar to what you can do with wasmtime, would be even more amazing 😄 ). I also absolutely agree with the arguments you are making regarding the introduction of tech debt that the feature would bring.

So, shall we maybe close this issue and maybe revisit the topic of how to minimize the binary size when we look at slightly more powerful targets and / or know exactly how much memory we would have available for the wasm runtime? What do you think?

[Robbepop]

@FedorSmirnov89 thank you for all the info and performance numbers.

I too wonder why "No Linker" and new_unchecked is not much better. However, in an experiment I conducted not long ago I also had issues getting the real picture of the binary size with a Wasmi compilation. It is kinda hard to get everything right and not optimized away etc.

What does "Module Size" and "Firmware Size" mean? Module size is the serialized moduel or the Wasm module? And firmware size is the Wasmi (+others) binary itself?

I honestly would have hoped that the combination of the Instance::new and Module::new_unchecked was more effective. (Maybe it was?) But it seems even if the numbers were better the gap between those and the (de)serialization feature of yours is quite big. So maybe it would be beneficial for Wasmi to include such a (de)serialization feature.

Would it be suitable for you if it was only possible to (de)serialize an Instance (+Store) and not a Module? (De)serialization of a Module will be impossible together with certain features planned for Wasmi, however Instance (de)serialization could still work.

[..] an option of running the module asynchronously, similar to what you can do with wasmtime, would be even more amazing 😄 )

Wasmi already supports async (or concurrent) executions via ResumableInvocation. It just works differently from Wasmtime in that Wasmi's API is a bit more low-level and provides the user with more control. But it certainly is already possible to pull it off. For an example of how to use this API to build a scheduler, see: https://github.com/wasmi-labs/wasmi/blob/main/crates/wast/src/lib.rs#L539

It is insane that tinywasm supports module (de)serialization and it works so well there. If it is indeed as powerful as measured we might want to add it to Wasmi eventually. Not a big fan though, since it will be a huge maintenance burden of how to manage deserialized modules with version changes and thus changes to Wasmi's internal structures etc. That's why I haven't even bothered thinking about such a feature so far.

So, shall we maybe close this issue and maybe revisit the topic of how to minimize the binary size when we look at slightly more powerful targets and / or know exactly how much memory we would have available for the wasm runtime? What do you think?

I ran out of ideas for now. Also I have no great numbers for you either. I am very sorry. :( The only thing I can seriously tell you is that I will work to make Wasmi the best Wasm runtime for constrained devices if it isn't already.

[FedorSmirnov89]

Hi @Robbepop :)

What does "Module Size" and "Firmware Size" mean? Module size is the serialized moduel or the Wasm module? And firmware size is the Wasmi (+others) binary itself?

"Firmware Size" is what probe-rs shows me as the amount of bytes it actually writes onto the board when flashing it with the firmware. The firmware contains three main parts:

1. The Wasm runtime and the code for its embedding into the firmware (host functions, etc.)
2. Embassy (minimal in this example, used to run a timer in parallel to test that I can stop the module execution without relying on it being written cooperatively - fuel consumption is great here :) )
3. The module which is statically written into the firmware

I don't exactly know how large the embassy contribution is to the firmware size, but I assume it to be roughly the same for all cases.

"Module Size" is the size of the module we load into the firmware. Added the info since it is easy to measure. So this number could be subtracted from the firmware size to get the impact of Wasm runtime + embassy.

Wasmi already supports async (or concurrent) executions via ResumableInvocation. It just works differently from Wasmtime in that Wasmi's API is a bit more low-level and provides the user with more control. But it certainly is already possible to pull it off. For an example of how to use this API to build a scheduler, see: https://github.com/wasmi-labs/wasmi/blob/main/crates/wast/src/lib.rs#L539

Ah ya. Having fuel consumption is awesome and in fact a hard requirement from my point of view since we want to be able to stop the module execution, even is module is not written cooperatively. So we need some mechanism which will make the module regularly yield to the host.

Sorry, I phrased it poorly when talking about "asynchronous execution like in wasmtime". What I meant was that it would be great to be able to link asynchronous host functions. Specifically on embedded, we are mostly single-threaded. At the same time, we have a lot of asynchronous events going on, e.g., interrupts. Using embassy is awesome here, but also means that accessing sensor values or interacting with peripherals almost always requires an asynchronous API. If we could define asynchronous host functions, we could have a much more ergonomic programming model for the .wasm modules we want to run on embedded (just started to experiment with the way of writing these modules though, so take all of this with a big grain of salt 😄 ).

Would it be suitable for you if it was only possible to (de)serialize an Instance (+Store) and not a Module? (De)serialization of a Module will be impossible together with certain features planned for Wasmi, however Instance (de)serialization could still work.

Absolutely. From the practical point of view, we either way need an extra step on the "build machine" which processes the .wasm file and produces something that is specific to the way we deploy the wasm runtime (but not specific to the concrete HW target). For instance, when working with tinywasm, the build machine first instruments the .wasm file to periodically call a specific host function (since tinywasm does not have fuel consumption) and then serializes the instrumented module, creating the payload which will be sent to the embedded target when we want to run the module.

In that process, it doesn't really matter whether we serialize the module or the instance. In fact, when we serialize the instance, we could potentially put even less things onto the embedded target, since we don't need anything required to instantiate the module, right?

If this makes sense as a direction to follow, I would be happy to spend some time exploring a serialization of the Instance. I think I likely can reuse a lot of the things in my current prototype branch, such as the roundtrip tests or the feature gating of the parsing machinery.

What do you think?

[Robbepop]

So we need some mechanism which will make the module regularly yield to the host.

That's perfectly possible with Wasmi's fuel metering combined with Wasmi's Func::call_resumable API.

Specifically on embedded, we are mostly single-threaded. At the same time, we have a lot of asynchronous events going on, e.g., interrupts.

To some extend you can emulate this as well with Wasmi's Func::call_resumable API. But this time not with Wasmi's fuel metering but with custom host errors that indicate that the system shall yield back, e.g. some kind of interrupt. The only downside is that these "interrupts" may only occur when calling the host. However, given that you have enough control over the host API you can design it so that a host function is called regularly, e.g. in a loop. This host function could then check for any interrupt signals in sensors (or whatever) and return this "interrupt" host error in that case. With this you have all you need via already existing Wasmi APIs if that's applicable.

In fact, when we serialize the instance, we could potentially put even less things onto the embedded target, since we don't need anything required to instantiate the module, right?

It depends. Generally, yes. But keep in mind that serializing Instance's is different from serializing Module's in that also the Instance's current state is serialized as well. This is perfect if that's what you want but not so great if you just want to create new Instance's from a Module's blue-print. If you always need a "fresh" Instance you might get away by adding a reset method that resets all the Instance related data, but this obviously is not ideal and may be very costly and in some cases not even possible.

If this makes sense as a direction to follow, I would be happy to spend some time exploring a serialization of the Instance. I think I likely can reuse a lot of the things in my current prototype branch, such as the roundtrip tests or the feature gating of the parsing machinery.

With Wasmi's current architecture we can do Module serialization (which is what you did) but with features that I had planned to implement for Wasmi this Module serialization will no longer be possible. We could start designing Instance serialization but the problem with that is that so many things are likely to change that it is probably not a great time investment for now. I might be wrong though as I am not 100% certain I already am seeing the big picture.

[FedorSmirnov89]

Ah, I see. So, maybe we will continue the exploration on our side a bit to get a better understanding of the resource requirements and other constraints we would have and then revisit this topic a bit later down the line. Just want to mention that if you do decide that it is a good time to explore serializing the Instance, I would be very happy to contribute to that.