Rust API

[jeromegn]

This PR adds a rudimentary Rust API for using libkrun. The idea is to make this new API the main one. The C API would use it entirely once this is done.

Ultimately, this new API should prevent unrepresentable states and allow usage from Rust in an ergonomic manner.

I am looking for early feedback before I continue my work. I'm trying not to touch much outside of the API surface (keeping other changes for when/if this PR is accepted).

Is the team open to this kind of change?

[ggoodman]

I understood from #411 and some discussions on the Matrix channel that there is an interest in making a rust API a first class citizen in a v2.

[jeromegn]

Didn’t know there was a matrix channel. I’ll join it if I can find it :) I’m doing this because I definitely need to expose a more advanced API I can use from rust. I’ve modified the virtio block device API to be a trait and I’ve implemented my own custom device which enables great performance for special use cases. It makes no sense to expose that as a C API. Or rather: it’s a non goal for me. Would it still be acceptable in v1? It’s not a breaking change.

…

On Sun, Dec 28, 2025 at 5:18 PM Geoff Goodman ***@***.***> wrote: *ggoodman* left a comment (containers/libkrun#494) <#494 (comment)> I understood from #411 <#411> and some discussions on the Matrix channel that there is an interest in making a rust API a first class citizen in a v2. — Reply to this email directly, view it on GitHub <#494 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAKSPIX6CSMV226OOKNDPD4EBJKZAVCNFSM6AAAAACQF4563OVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMOJVGA4TGOBTGM> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[mtjhrc]

So I like the direction you took with the API design, it seems like a reasonable stepping stone between v1 and v2 libkrun. There are some other things we want in the v2 API such as to make everything more explicit - not adding or configuring the virtio devices based on heuristics and I think we also need a clear plan to interact with a running VM.

I am a bit concerned about 2 things:

• breaking something when refactoring the whole API surface implementation (we can mitigate that if we are careful and test the new changes here)
• Do we want/need the Rust API to be stable until libkrun v2?

I’m doing this because I definitely need to expose a more advanced API I
can use from rust. I’ve modified the virtio block device API to be a trait

It makes no sense to expose that as a C API. Or rather: it’s a non goal for me.

Yeah, this is currently problematic, I ran into this when I implemented the gpu display output support. We actually already expose some traits as a C API - specifically the traits in krun_input and krun_display crates, but it is very annoying (and error prone) to expose new traits like that.

These traits are actually implemented by the Rust gui_vm example (via the krun_gtk_display example/reference implementation). The annoying part is that libkrun is written in Rust and the example is also written in Rust, but the function calls have to go through the C API. So the bindings are actually bidirectional (basically constructing a struct with function pointers from a trait + implementing the trait for the struct with function pointers).

I am hoping to simplify this situation eventually with v2 - since we would have a native Rust API we could drop one side of the bindings, and also possibly partially automate the generation of the C bindings via macros. This could then also be used to expose the hooks you would implement for the virtio block as a C API.

I’ve modified the virtio block device API to be a trait
and I’ve implemented my own custom device which enables great performance
for special use cases.

This to me seems quite difficult to get right, if we expose a very fine grained API, we could end up locking ourselves into how the internals of libkrun work, which could impede refactoring and performance optimizations within libkrun itself, so we have to be careful with that.

[mtjhrc]

Ok, so we had a meeting today and I asked the other maintainers what they think. We concluded that we can proceed forward with this for v1 too.

I have some thoughts:

• please split changes into commits and don't mix in irrelevant changes (e.g. the formatting)
• I feel like before changing the implementation of the C API functions, adding some simple unit tests that assert the state of the builder after calling the functions would be helpful. This could simplify the review process, and make sure we don't break anything. (especially the convoluted to-be-deprecated implicit APIs)
• put the C API and Rust API in separate files
• I like that you separated the step of building VM and running the VM

Thanks!

[jeromegn]

Thanks for bringing it up at your meeting! That all sounds reasonable to me. I don't know exactly when / if I'll get to completing this.

If I don't get to it, at least it gives others some idea of how to do it.