docs/devel/rust.rst

3 Rust in QEMU
6 Rust in QEMU is a project to enable using the Rust programming language
10 from ``SysBusDevice`` in `*safe*`__ Rust.  Later, it may become possible
14 __ https://doc.rust-lang.org/nomicon/meet-safe-and-unsafe.html
16 Building the Rust in QEMU code
17 ------------------------------
19 The Rust in QEMU code is included in the emulators via Meson.  Meson
25 are accustomed to the more "normal" Cargo-based development workflow.
29   comes from the ``rust/Cargo.toml`` workspace file
31 * it is also possible to use ``cargo`` for common Rust-specific coding
36 output directory (typically ``rust/target/``).  A vanilla invocation
46 A target for ``rustfmt`` is also declared in ``rust/meson.build``:
53     pyvenv/bin/meson devenv -w ../rust cargo clippy --tests
54     pyvenv/bin/meson devenv -w ../rust cargo fmt
62   tree.  This third method is useful if you are using ``rust-analyzer``;
64   ``rust-analyzer.cargo.extraEnv`` setting.
66 As shown above, you can use the ``--tests`` option as usual to operate on test
71    make check-rust
75 Supported tools
99 * NUL-terminated file names with ``#[track_caller]`` are scheduled for
102   ``util/error.c`` to support non-NUL-terminated file names.
108 __ https://github.com/rust-lang/rust/pull/125258
111 ``--generate-cstr``.  This option requires version 0.66.x and will
115 Writing Rust code in QEMU
116 -------------------------
125 * ``pl011`` (under ``rust/hw/char/pl011``) and ``hpet`` (under ``rust/hw/timer/hpet``)
141 - *complete*: ready for use in new devices; if applicable, the API supports the
144 - *stable*: ready for production use, the API is safe and should not undergo
147 - *proof of concept*: the API is subject to change but allows working with safe
148   Rust
150 - *initial*: the API is in its initial stages; it requires large amount of
151   unsafe code; it might have soundness or type-safety issues
186 Generally speaking, these are all removed in the corresponding Rust functions:
217 provide extra compile-time checking; the basic *realize* functionality
227 Rust has very strict rules with respect to how you get an exclusive (``&mut``)
252 __ https://github.com/rust-lang/miri
254 Almost all Rust code in QEMU will involve QOM objects, and pointers to these
273 to a Rust mutable reference, and use a shared reference instead.  The
275 Rust compiler about interior mutability, and optionally to enforce locking
277 also be provided for ``AioContext``-based locking as well.
282 crate, which is able to "look inside" them when building an in-memory
297 then manually check for the big QEMU lock with assertions, which allows
298 the wrapper to be declared thread-safe::
310   Rust bindings.  If the C code uses ``offsetof``, look at qdev properties
319   (either a builtin one or a user-defined one) in order to pass it to C
322   for the fields of a Rust ``struct``.
328   in Rust, they can be stored in traits and then turned into ``static``
331 **Document limitations due to old Rust versions**
333   supported set of Rust versions, document it in the source and in this
361     pub fn derive_object(input: TokenStream) -> TokenStream {
373     fn derive_object_or_error(input: DeriveInput) ->
389 * Extracting information from Rust source code into traits, typically based
405 Right now, only the nightly version of ``rustfmt`` is supported.  This
407 ``cargo fmt --check``, maintainers can fix this for you when applying patches.
413 -------------------
427 The versions specified in ``rust/Cargo.lock`` must be the same as the
428 subprojects; note that the ``rust/`` directory forms a Cargo `workspace`__,
431 __ https://doc.rust-lang.org/cargo/reference/workspaces.html#virtual-workspace
434 Rust version (|msrv|).
437 crate.  The wrap file must be named ``NAME-SEMVER-rs.wrap``, where ``NAME``
439 first non-zero number.  For example, a crate with version ``0.2.3`` will use
443 ``subprojects/NAME-SEMVER-rs/meson.build``.  Generally this includes:
447 * a ``static_library`` or ``rust.proc_macro`` line to perform the actual build
456 non-native versions of the crate.
462 * the ``--cfg`` (which have to be "reverse engineered" from the ``build.rs``
465 * usually, a ``--cap-lints allow`` argument to hide warnings from rustc
469 version with ``meson subprojects update --reset ``NAME-SEMVER-rs``.  This might
476 As a last step, add the new subproject to ``scripts/archive-source.sh``,
477 ``scripts/make-release`` and ``subprojects/.gitignore``.