motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-08-04 08:13:54 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

* scripts: dump stdin on meson-buildoptions error

Browse source 
* rust: introduce qemu_api::cell::Opaque<>
 * rust: express pinning requirements for timers
 * rust: hpet: decode HPET registers into enums
 * rust: cell: add full example of declaring a SysBusDevice
 * rust: qom: remove operations on &mut
 -----BEGIN PGP SIGNATURE-----
 
 iQFIBAABCAAyFiEE8TM4V0tmI4mGbHaCv/vSX3jHroMFAmfNbXwUHHBib256aW5p
 QHJlZGhhdC5jb20ACgkQv/vSX3jHroNjpwf+ODnG0XzHt7LSag695zs5fVLK353m
 vLAHJ0bsmHoR4V+jEc+eaY7esDx5TLB9SRX/NvDsumJ9xnGYxXVn8Ti5GNHpa/xd
 qSReB6X3E8fqG5e3AffUJGJnxrD8dHJ733RsyJBZqJc9sWkUnSiEBb5lGu7br6oC
 fFyfiGweYboQ4AsiQUDtEN+tQsTWNkdThYEzq+dpnZrDJHNnw5e/rRwmqCUnEsLU
 PfwhrOGJ3OkIUtdgHStuNfiN9sqjXV5DXmZVa9L2We8FEQdkhBzg3TC0ez0gFG/1
 W0P6JwfWk9Z+y/ERxkaycSXmabM0zUiFF1UJNgKEXp5iuPnRFC82OtRSUg==
 =de1b
 -----END PGP SIGNATURE-----

Merge tag 'for-upstream' of https://gitlab.com/bonzini/qemu into staging

* scripts: dump stdin on meson-buildoptions error
* rust: introduce qemu_api::cell::Opaque<>
* rust: express pinning requirements for timers
* rust: hpet: decode HPET registers into enums
* rust: cell: add full example of declaring a SysBusDevice
* rust: qom: remove operations on &mut

# -----BEGIN PGP SIGNATURE-----
#
# iQFIBAABCAAyFiEE8TM4V0tmI4mGbHaCv/vSX3jHroMFAmfNbXwUHHBib256aW5p
# QHJlZGhhdC5jb20ACgkQv/vSX3jHroNjpwf+ODnG0XzHt7LSag695zs5fVLK353m
# vLAHJ0bsmHoR4V+jEc+eaY7esDx5TLB9SRX/NvDsumJ9xnGYxXVn8Ti5GNHpa/xd
# qSReB6X3E8fqG5e3AffUJGJnxrD8dHJ733RsyJBZqJc9sWkUnSiEBb5lGu7br6oC
# fFyfiGweYboQ4AsiQUDtEN+tQsTWNkdThYEzq+dpnZrDJHNnw5e/rRwmqCUnEsLU
# PfwhrOGJ3OkIUtdgHStuNfiN9sqjXV5DXmZVa9L2We8FEQdkhBzg3TC0ez0gFG/1
# W0P6JwfWk9Z+y/ERxkaycSXmabM0zUiFF1UJNgKEXp5iuPnRFC82OtRSUg==
# =de1b
# -----END PGP SIGNATURE-----
# gpg: Signature made Sun 09 Mar 2025 18:29:16 HKT
# gpg:                using RSA key F13338574B662389866C7682BFFBD25F78C7AE83
# gpg:                issuer "pbonzini@redhat.com"
# gpg: Good signature from "Paolo Bonzini <bonzini@gnu.org>" [full]
# gpg:                 aka "Paolo Bonzini <pbonzini@redhat.com>" [full]
# Primary key fingerprint: 46F5 9FBD 57D6 12E7 BFD4  E2F7 7E15 100C CD36 69B1
#      Subkey fingerprint: F133 3857 4B66 2389 866C  7682 BFFB D25F 78C7 AE83

* tag 'for-upstream' of https://gitlab.com/bonzini/qemu: (25 commits)
  rust: pl011: Allow NULL chardev argument to pl011_create()
  meson.build: default to -gsplit-dwarf for debug info
  rust: qom: remove operations on &mut
  rust: cell: add full example of declaring a SysBusDevice
  rust: hpet: decode HPET registers into enums
  rust: pl011: pass around registers::Data
  rust: pl011: switch to safe chardev operation
  rust: pl011: clean up visibilities of callbacks
  rust: pl011: move register definitions out of lib.rs
  rust: chardev: provide basic bindings to character devices
  rust: bindings: remove more unnecessary Send/Sync impls
  rust: chardev: wrap Chardev with Opaque<>
  rust: memory: wrap MemoryRegion with Opaque<>
  rust: sysbus: wrap SysBusDevice with Opaque<>
  rust: hpet: do not access fields of SysBusDevice
  rust: qdev: wrap Clock and DeviceState with Opaque<>
  rust: qom: wrap Object with Opaque<>
  rust: irq: wrap IRQState with Opaque<>
  rust: timer: wrap QEMUTimer with Opaque<> and express pinning requirements
  rust: hpet: embed Timer without the Option and Box indirection
  ...

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
This commit is contained in:
Stefan Hajnoczi 2025-03-10 13:40:05 +08:00
commit 1843a0c01d
25 changed files with 1551 additions and 1010 deletions
Download patch file Download diff file Expand all files Collapse all files

36
docs/devel/rust.rst
View file

@ -296,15 +296,35 @@ of ``&mut self``; access to internal fields must use *interior mutability*
to go from a shared reference to a ``&mut``.
Whenever C code provides you with an opaque ``void *``, avoid converting it
to a Rust mutable reference, and use a shared reference instead. Rust code
will then have to use QEMU's ``BqlRefCell`` and ``BqlCell`` type, which
enforce that locking rules for the "Big QEMU Lock" are respected. These cell
types are also known to the ``vmstate`` crate, which is able to "look inside"
them when building an in-memory representation of a ``struct``'s layout.
Note that the same is not true of a ``RefCell`` or ``Mutex``.
to a Rust mutable reference, and use a shared reference instead. The
``qemu_api::cell`` module provides wrappers that can be used to tell the
Rust compiler about interior mutability, and optionally to enforce locking
rules for the "Big QEMU Lock". In the future, similar cell types might
also be provided for ``AioContext``-based locking as well.
In the future, similar cell types might also be provided for ``AioContext``-based
locking as well.
In particular, device code will usually rely on the ``BqlRefCell`` and
``BqlCell`` type to ensure that data is accessed correctly under the
"Big QEMU Lock". These cell types are also known to the ``vmstate``
crate, which is able to "look inside" them when building an in-memory
representation of a ``struct``'s layout. Note that the same is not true
of a ``RefCell`` or ``Mutex``.
Bindings code instead will usually use the ``Opaque`` type, which hides
the contents of the underlying struct and can be easily converted to
a raw pointer, for use in calls to C functions. It can be used for
example as follows::
#[repr(transparent)]
#[derive(Debug, qemu_api_macros::Wrapper)]
pub struct Object(Opaque<bindings::Object>);
where the special ``derive`` macro provides useful methods such as
``from_raw``, ``as_ptr`, ``as_mut_ptr`` and ``raw_get``. The bindings will
then manually check for the big QEMU lock with assertions, which allows
the wrapper to be declared thread-safe::
unsafe impl Send for Object {}
unsafe impl Sync for Object {}
Writing bindings to C code
''''''''''''''''''''''''''