[v2,00/12] rust: wrap all C types exposed through qemu_api

Message

Paolo Bonzini Feb. 27, 2025, 2:22 p.m. UTC

This is the second part of "rust: prepare for splitting crates" with
Zhao's suggestions addressed and with more precise handling of pinning
for Timers.

The series introduce a third generic type in qemu_api::cell, Opaque<T>.
This type is similar to a same-named type in Linux; it is basically a
"disable all undefined behavior" switch for the Rust compiler and it
helps maintaining safety at the Rust/C boundary, complementing the
existing BqlCell and BqlRefCell types.

Apart from making things more formally correct, this makes it possible
to implement methods on a struct that is distinct from the one produced
by bindgen.  This has a couple of advantages:

- you do not have to disable the Copy trait on structs where you want
  to add a Drop trait.  This was already a problem for the Timer struct.

- whether Send and Sync are implemented is entirely a decision of the
  place that implements the wrapper.  Previously, a struct with no
  pointers for example would have been always both Send and Sync,
  whereas now that can be adjusted depending on the actual
  thread-safety of the Rust methods.

- more pertinent to the "multiple crates" plan that prompted posting
  of v1, you do not have to put the methods in the same crate as the
  bindgen-generated bindings.inc.rs.

It also makes Debug output a bit less unwieldy, and in the future one
might want to add specialized implementations of Display and Debug that
are both useful and readable.

Paolo

Supersedes: <[e-mail]>

v1->v2:
From Zhao's review:
- fix Opaque::zeroed()
- improve comments for as_mut_ptr() fand as_void_ptr()
- remove unnecessary ".0" accesses, or highlight why they're needed
- add patch to access SysBusDevice MMIO addresses safely

Other changes:
- improve safety comments for constructors of Opaque
- remove implementation of Default for Opaque<T: Default>,
  leaving Opaque::new() in but only as an unsafe function
- change Timer patch to construct timers as Pin<Box<Self>>,
  following the documentation of `Opaque<>`
- add "rust: vmstate: add std::pin::Pin as transparent wrapper"

Paolo Bonzini (12):
  rust: cell: add wrapper for FFI types
  rust: qemu_api_macros: add Wrapper derive macro
  rust: vmstate: add std::pin::Pin as transparent wrapper
  rust: timer: wrap QEMUTimer with Opaque<> and express pinning
    requirements
  rust: irq: wrap IRQState with Opaque<>
  rust: qom: wrap Object with Opaque<>
  rust: qdev: wrap Clock and DeviceState with Opaque<>
  rust: hpet: do not access fields of SysBusDevice
  rust: sysbus: wrap SysBusDevice with Opaque<>
  rust: memory: wrap MemoryRegion with Opaque<>
  rust: chardev: wrap Chardev with Opaque<>
  rust: bindings: remove more unnecessary Send/Sync impls

 docs/devel/rust.rst             |  36 +++--
 meson.build                     |   7 -
 rust/hw/timer/hpet/src/hpet.rs  |  27 ++--
 rust/qemu-api-macros/src/lib.rs |  86 +++++++++++-
 rust/qemu-api/meson.build       |   7 +-
 rust/qemu-api/src/bindings.rs   |  26 +---
 rust/qemu-api/src/cell.rs       | 228 +++++++++++++++++++++++++++++++-
 rust/qemu-api/src/chardev.rs    |   8 +-
 rust/qemu-api/src/irq.rs        |  15 ++-
 rust/qemu-api/src/memory.rs     |  37 +++---
 rust/qemu-api/src/qdev.rs       |  75 +++++++----
 rust/qemu-api/src/qom.rs        |  35 +++--
 rust/qemu-api/src/sysbus.rs     |  40 +++++-
 rust/qemu-api/src/timer.rs      |  47 ++++---
 rust/qemu-api/src/vmstate.rs    |   3 +-
 15 files changed, 527 insertions(+), 150 deletions(-)