rust: cell: add BQL-enforcing Cell variant

QEMU objects usually have their pointer shared with the "outside
world" very early in their lifetime, for example when they create their
MemoryRegions. Be

rust: cell: add BQL-enforcing Cell variant

QEMU objects usually have their pointer shared with the "outside
world" very early in their lifetime, for example when they create their
MemoryRegions. Because at this point it is not valid anymore to
create a &mut reference to the device, individual parts of the
device struct must be made mutable in a controlled manner.

QEMU's Big Lock (BQL) effectively turns multi-threaded code into
single-threaded code while device code runs, as long as the BQL is not
released while the device is borrowed (because C code could sneak in and
mutate the device). We can then introduce custom interior mutability primitives
that are semantically similar to the standard library's (single-threaded)
Cell and RefCell, but account for QEMU's threading model. Accessing
the "BqlCell" or borrowing the "BqlRefCell" requires proving that the
BQL is held, and attempting to access without the BQL is a runtime panic,
similar to RefCell's already-borrowed panic.

With respect to naming I also considered omitting the "Bql" prefix or
moving it to the module, e.g. qemu_api::bql::{Cell, RefCell}. However,
this could easily lead to mistakes and confusion; for example rustc could
suggest the wrong import, leading to subtle bugs.

As a start introduce the an equivalent of Cell. Almost all of the code
was taken from Rust's standard library, while removing unstable features
and probably-unnecessary functionality that constitute a large of the
original code. A lot of what's left is documentation, as well as unit
tests in the form of doctests. These are not yet integrated in "make
check" but can be run with "cargo test --doc".

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust/qemu-api: Fix fragment-specifiers in define_property macro

For the matcher of macro, "expr" is used for expressions, while "ident"
is used for variable/function names, and "ty" matches types.

rust/qemu-api: Fix fragment-specifiers in define_property macro

For the matcher of macro, "expr" is used for expressions, while "ident"
is used for variable/function names, and "ty" matches types.

In define_property macro, $field is a member name of type $state, so it
should be defined as "ident", though offset_of! doesn't complain about
this. $type is the type of $field, since it is not used in the macro, so
that no type mismatch error is triggered either.

Fix fragment-specifiers of $field and $type.

Signed-off-by: Junjie Mao <junjie.mao@hotmail.com>
Co-developed-by: Zhao Liu <zhao1.liu@intel.com>
Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
Link: https://lore.kernel.org/r/20241017143245.1248589-2-zhao1.liu@intel.com
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: fix doc test syntax

Allow "cargo test --doc" to pass.

Reviewed-by: Junjie Mao <junjie.mao@hotmail.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

rust: build: add "make clippy", "make rustfmt", "make rustdoc"

Abstract common invocations of "cargo", that do not require copying
the generated bindgen file or setting up MESON_BUILD_ROOT.

In the

rust: build: add "make clippy", "make rustfmt", "make rustdoc"

Abstract common invocations of "cargo", that do not require copying
the generated bindgen file or setting up MESON_BUILD_ROOT.

In the future these could also do completely without cargo and invoke
the underlying programs directly.

Reviewed-by: Junjie Mao <junjie.mao@hotmail.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: build: establish a baseline of lints across all crates

Many lints that default to allow can be helpful in detecting bugs or
keeping the code style homogeneous. Add them liberally, though perh

rust: build: establish a baseline of lints across all crates

Many lints that default to allow can be helpful in detecting bugs or
keeping the code style homogeneous. Add them liberally, though perhaps
not as liberally as in hw/char/pl011/src/lib.rs. In particular, enabling
entire groups can be problematic because of bitrot when new links are
added in the future.

For Clippy, this is actually a feature that is only present in Cargo
1.74.0 but, since we are not using Cargo to *build* QEMU, only developers
will need a new-enough cargo and only to run tools such as clippy.
The requirement does not apply to distros that are building QEMU.

Reviewed-by: Junjie Mao <junjie.mao@hotmail.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: fix a couple style issues from clippy

These are reported as clippy::semicolon_inside_block and clippy::as_ptr_cast_mut.

clippy::semicolon_inside_block can be configured not to lint single-lin

rust: fix a couple style issues from clippy

These are reported as clippy::semicolon_inside_block and clippy::as_ptr_cast_mut.

clippy::semicolon_inside_block can be configured not to lint single-line
blocks; just go with the default.

Reviewed-by: Junjie Mao <junjie.mao@hotmail.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: cargo: store desired warning levels in workspace Cargo.toml

An extra benefit of workspaces is that they allow to place lint level
settings in a single Cargo.toml; the settings are then inherit

rust: cargo: store desired warning levels in workspace Cargo.toml

An extra benefit of workspaces is that they allow to place lint level
settings in a single Cargo.toml; the settings are then inherited by
packages in the workspace.

Correspondingly, teach rustc_args.py to get the unexpected_cfgs
configuration from the workspace Cargo.toml.

Note that it is still possible to allow or deny warnings per crate or
module, via the #![] attribute syntax. The rust/qemu-api/src/bindings.rs
file is an example.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: build: generate lint flags from Cargo.toml

Cargo.toml makes it possible to describe the desired lint level settings
in a nice format. We can extend this to Meson-built crates, by teaching
rus

rust: build: generate lint flags from Cargo.toml

Cargo.toml makes it possible to describe the desired lint level settings
in a nice format. We can extend this to Meson-built crates, by teaching
rustc_args.py to fetch lint and --check-cfg arguments from Cargo.toml.
--check-cfg arguments come from the unexpected_cfgs lint as well as crate
features

Start with qemu-api, since it already has a [lints.rust] table and
an invocation of rustc_args.py.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: build: restrict --cfg generation to only required symbols

Parse the Cargo.toml file, looking for the unexpected_cfgs
configuration. When generating --cfg options from the
config-host.h file,

rust: build: restrict --cfg generation to only required symbols

Parse the Cargo.toml file, looking for the unexpected_cfgs
configuration. When generating --cfg options from the
config-host.h file, only use those that are included in the
configuration.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: build: move rustc_args.py invocation to qemu-api crate

Only qemu-api needs access to the symbols in config-host.h. Remove
the temptation to use them elsewhere by limiting the --cfg arguments

rust: build: move rustc_args.py invocation to qemu-api crate

Only qemu-api needs access to the symbols in config-host.h. Remove
the temptation to use them elsewhere by limiting the --cfg arguments to
the qemu-api crate.

Per-crate invocation of the script will also be needed to add --check-cfg
options for each crate's features (when more complex, build-time
configurable devices are added in the future).

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: allow using build-root bindings.rs from cargo

Right now, using cargo with QEMU requires copying by hand the bindings.rs to the
source tree. Instead, we can use an include file to escape the c

rust: allow using build-root bindings.rs from cargo

Right now, using cargo with QEMU requires copying by hand the bindings.rs to the
source tree. Instead, we can use an include file to escape the cage of cargo's
mandated source directory structure.

By running cargo within meson's "devenv" and adding a MESON_BUILD_ROOT
environment variable, it is easy for build.rs to find the file. However, the
file must be symlinked into cargo's output directory for rust-analyzer to find
it.

Suggested-by: Junjie Mao <junjie.mao@hotmail.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: apply --cfg MESON to all crates

We might have more uses for --cfg MESON, even though right now it's only
qemu-api that has generated files. Since we're going to add more flags
to the add_proj

rust: apply --cfg MESON to all crates

We might have more uses for --cfg MESON, even though right now it's only
qemu-api that has generated files. Since we're going to add more flags
to the add_project_arguments calls for Rust, it makes sense to also add
--cfg MESON everywhere.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: do not use --generate-cstr

--generate-cstr is a good idea and generally the right thing to do,
but it is not available in Debian 12 and Ubuntu 22.04. Work around
the absence.

Signed-off-by:

rust: do not use --generate-cstr

--generate-cstr is a good idea and generally the right thing to do,
but it is not available in Debian 12 and Ubuntu 22.04. Work around
the absence.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: do not use MaybeUninit::zeroed()

MaybeUninit::zeroed() is handy but is not available as a "const" function
until Rust 1.75.0.

Remove the default implementation of Zeroable::ZERO, and write by

rust: do not use MaybeUninit::zeroed()

MaybeUninit::zeroed() is handy but is not available as a "const" function
until Rust 1.75.0.

Remove the default implementation of Zeroable::ZERO, and write by hand
the definitions for those types that need it. It may be possible to
add automatic implementation of the trait, via a procedural macro and/or
a trick similar to offset_of!, but do it the easy way for now.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: introduce alternative implementation of offset_of!

offset_of! was stabilized in Rust 1.77.0. Use an alternative implemenation
that was found on the Rust forums, and whose author agreed to lic

rust: introduce alternative implementation of offset_of!

offset_of! was stabilized in Rust 1.77.0. Use an alternative implemenation
that was found on the Rust forums, and whose author agreed to license as
MIT for use in QEMU.

The alternative allows only one level of field access, but apart
from this can be used just by replacing core::mem::offset_of! with
qemu_api::offset_of!.

The actual implementation of offset_of! is done in a declarative macro,
but for simplicity and to avoid introducing an extra level of indentation,
the trigger is a procedural macro #[derive(offsets)].

The procedural macro is perhaps a bit overengineered, but it helps
introducing some idioms that will be useful in the future as well.

Signed-off-by: Junjie Mao <junjie.mao@hotmail.com>
Co-developed-by: Paolo Bonzini <pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: create a cargo workspace

Workspaces allows tracking dependencies for multiple crates at once,
by having a single Cargo.lock file at the top of the rust/ tree.
Because QEMU's Cargo.lock files h

rust: create a cargo workspace

Workspaces allows tracking dependencies for multiple crates at once,
by having a single Cargo.lock file at the top of the rust/ tree.
Because QEMU's Cargo.lock files have to be synchronized with the versions
of crates in subprojects/, using a workspace avoids the need to copy
over the Cargo.lock file when adding a new device (and thus a new crate)
under rust/hw/.

In addition, workspaces let cargo download and build dependencies just
once. While right now we have one leaf crate (hw/char/pl011), this
will not be the case once more devices are added.

Reviewed-by: Zhao Liu <zhao1.liu@intel.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: synchronize dependencies between subprojects and Cargo.lock

The next commit will introduce a new build.rs dependency for rust/qemu-api,
version_check. Before adding it, ensure that all depend

rust: synchronize dependencies between subprojects and Cargo.lock

The next commit will introduce a new build.rs dependency for rust/qemu-api,
version_check. Before adding it, ensure that all dependencies are
synchronized between the Meson- and cargo-based build systems.

Note that it's not clear whether in the long term we'll use Cargo for
anything; it seems that the three main uses (clippy, rustfmt, rustdoc)
can all be invoked manually---either via glue code in QEMU, or by
extending Meson to gain the relevant functionality. However, for
the time being we're stuck with Cargo so it should at least look at
the same code as the rest of the build system.

Reviewed-by: Zhao Liu <zhao1.liu@intel.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: introduce a c_str macro

This allows CStr constants to be defined easily on Rust 1.63.0, while
checking that there are no embedded NULs. c"" literals were only
stabilized in Rust 1.77.0.

Revi

rust: introduce a c_str macro

This allows CStr constants to be defined easily on Rust 1.63.0, while
checking that there are no embedded NULs. c"" literals were only
stabilized in Rust 1.77.0.

Reviewed-by: Zhao Liu <zhao1.liu@intel.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: use std::os::raw instead of core::ffi

core::ffi::c_* types were introduced in Rust 1.64.0. Use the older types
in std::os::raw, which are now aliases of the types in core::ffi. There is
no n

rust: use std::os::raw instead of core::ffi

core::ffi::c_* types were introduced in Rust 1.64.0. Use the older types
in std::os::raw, which are now aliases of the types in core::ffi. There is
no need to compile QEMU as no_std, so this is acceptable as long as we support
a version of Debian with Rust 1.63.0.

Reviewed-by: Zhao Liu <zhao1.liu@intel.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: add definitions for vmstate

Add a new qemu_api module, `vmstate`. Declare a bunch of Rust
macros declared that are equivalent in spirit to the C macros in
include/migration/vmstate.h.

For exa

rust: add definitions for vmstate

Add a new qemu_api module, `vmstate`. Declare a bunch of Rust
macros declared that are equivalent in spirit to the C macros in
include/migration/vmstate.h.

For example the Rust of equivalent of the C macro:

VMSTATE_UINT32(field_name, struct_name)

is:

vmstate_uint32!(field_name, StructName)

This breathtaking development will allow us to reach feature parity between
the Rust and C pl011 implementations.

Extracted from a patch by Manos Pitsidianakis
(https://lore.kernel.org/qemu-devel/20241024-rust-round-2-v1-4-051e7a25b978@linaro.org/).

Signed-off-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: provide safe wrapper for MaybeUninit::zeroed()

MaybeUninit::zeroed() is handy, but it introduces unsafe (and has a
pretty heavy syntax in general). Introduce a trait that provides the
same fu

rust: provide safe wrapper for MaybeUninit::zeroed()

MaybeUninit::zeroed() is handy, but it introduces unsafe (and has a
pretty heavy syntax in general). Introduce a trait that provides the
same functionality while staying within safe Rust.

In addition, MaybeUninit::zeroed() is not available as a "const"
function until Rust 1.75.0, so this also prepares for having handwritten
implementations of the trait until we can assume that version.

Reviewed-by: Junjie Mao <junjie.mao@hotmail.com>
Reviewed-by: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: make properties array immutable

Now that device_class_set_props() takes a const pointer, the only part of
"define_property!" that needs to be non-const is the call to try_into().
This in turn

rust: make properties array immutable

Now that device_class_set_props() takes a const pointer, the only part of
"define_property!" that needs to be non-const is the call to try_into().
This in turn will only break if offset_of returns a value with the most
significant bit set (i.e. a struct size that is >=2^31 or >= 2^63,
respectively on 32- and 64-bit system), which is impossible.

Just use a cast and clean everything up to remove the run-time
initialization. This also removes a use of OnceLock, which was only
stabilized in 1.70.0.

Reviewed-by: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: clean up define_property macro

Use the "struct update" syntax to initialize most of the fields to zero,
and simplify the handmade type-checking of $name.

Reviewed-by: Junjie Mao <junjie.mao@h

rust: clean up define_property macro

Use the "struct update" syntax to initialize most of the fields to zero,
and simplify the handmade type-checking of $name.

Reviewed-by: Junjie Mao <junjie.mao@hotmail.com>
Reviewed-by: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: cleanup module_init!, use it from #[derive(Object)]

Remove the duplicate code by using the module_init! macro; at the same time,
simplify how module_init! is used, by taking inspiration from t

rust: cleanup module_init!, use it from #[derive(Object)]

Remove the duplicate code by using the module_init! macro; at the same time,
simplify how module_init! is used, by taking inspiration from the implementation
of #[derive(Object)].

Reviewed-by: Junjie Mao <junjie.mao@hotmail.com>
Reviewed-by: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

rust: build integration test for the qemu_api crate

Adjust the integration test to compile with a subset of QEMU object
files, and make it actually create an object of the class it defines.

Follow

rust: build integration test for the qemu_api crate

Adjust the integration test to compile with a subset of QEMU object
files, and make it actually create an object of the class it defines.

Follow the Rust filesystem conventions, where tests go in tests/ if
they use the library in the same way any other code would.

Reviewed-by: Junjie Mao <junjie.mao@hotmail.com>
Reviewed-by: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...