diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/about/build-platforms.rst | 17 | ||||
| -rw-r--r-- | docs/devel/rust.rst | 93 | ||||
| -rw-r--r-- | docs/devel/tcg-icount.rst | 2 |
3 files changed, 52 insertions, 60 deletions
diff --git a/docs/about/build-platforms.rst b/docs/about/build-platforms.rst index 8671c3be9c..0160d3adb8 100644 --- a/docs/about/build-platforms.rst +++ b/docs/about/build-platforms.rst @@ -118,14 +118,15 @@ Rust build dependencies include bindgen or have an older version, it is recommended to install a newer version using ``cargo install bindgen-cli``. - QEMU requires Rust 1.77.0. This is available on all supported platforms - with one exception, namely the ``mips64el`` architecture on Debian bookworm. - For all other architectures, Debian bookworm provides a new-enough Rust - compiler in the ``rustc-web`` package. - - Also, on Ubuntu 22.04 or 24.04 this requires the ``rustc-1.77`` - (or newer) package. The path to ``rustc`` and ``rustdoc`` must be - provided manually to the configure script. + QEMU requires Rust 1.83.0. This is available on all supported platforms + with two exception: Ubuntu LTS releases 22.04 and 24.04, and the + ``mips64el`` architecture on Debian bookworm. For all other + architectures, Debian bookworm provides a new-enough Rust compiler + in the ``rustc-web`` package. + + It is expected that in the future Ubuntu will provide updated packages + like the existing ``rustc-1.82`` package. The path to ``rustc`` and + ``rustdoc`` will have to be provided manually to the configure script. Some distros prefer to avoid vendored crate sources, and instead use local sources from e.g. ``/usr/share/cargo/registry``. QEMU includes a diff --git a/docs/devel/rust.rst b/docs/devel/rust.rst index b6737536c6..13a20e86a1 100644 --- a/docs/devel/rust.rst +++ b/docs/devel/rust.rst @@ -1,4 +1,4 @@ -.. |msrv| replace:: 1.63.0 +.. |msrv| replace:: 1.83.0 Rust in QEMU ============ @@ -75,35 +75,23 @@ Note that doctests require all ``.o`` files from the build to be available. Supported tools ''''''''''''''' -QEMU supports rustc version 1.77.0 and newer. Notably, the following features -are missing: +QEMU supports rustc version 1.83.0 and newer. The following features +from relatively new versions of Rust are not used for historical reasons; +patches are welcome: -* inline const expression (stable in 1.79.0), currently worked around with - associated constants in the ``FnCall`` trait. - -* associated constants have to be explicitly marked ``'static`` (`changed in +* associated constants are still explicitly marked ``'static`` (`changed in 1.81.0`__) -* ``&raw`` (stable in 1.82.0). Use ``addr_of!`` and ``addr_of_mut!`` instead, - though hopefully the need for raw pointers will go down over time. - -* ``new_uninit`` (stable in 1.82.0). This is used internally by the ``pinned_init`` - crate, which is planned for inclusion in QEMU, but it can be easily patched - out. - -* referencing statics in constants (stable in 1.83.0). For now use a const - function; this is an important limitation for QEMU's migration stream - architecture (VMState). Right now, VMState lacks type safety because - it is hard to place the ``VMStateField`` definitions in traits. +* ``&raw`` (stable in 1.82.0). * NUL-terminated file names with ``#[track_caller]`` are scheduled for inclusion as ``#![feature(location_file_nul)]``, but it will be a while before QEMU can use them. For now, there is special code in ``util/error.c`` to support non-NUL-terminated file names. -* associated const equality would be nice to have for some users of - ``callbacks::FnCall``, but is still experimental. ``ASSERT_IS_SOME`` - replaces it. +Associated const equality would be nice to have for some users of +``callbacks::FnCall``, but is still experimental. Const assertions +are used instead. __ https://github.com/rust-lang/rust/pull/125258 @@ -115,15 +103,18 @@ anymore. Writing Rust code in QEMU ------------------------- -QEMU includes four crates: +QEMU includes several crates: + +* ``common`` provides Rust-only utilities -* ``qemu_api`` for bindings to C code and useful functionality +* ``bql``, ``chardev``, ``hw/core``, ``migration``, ``qom``, ``system``, + ``util`` for bindings to respective QEMU C library APIs -* ``qemu_api_macros`` defines several procedural macros that are useful when +* ``qemu_macros`` defines several procedural macros that are useful when writing C code * ``pl011`` (under ``rust/hw/char/pl011``) and ``hpet`` (under ``rust/hw/timer/hpet``) - are sample devices that demonstrate ``qemu_api`` and ``qemu_api_macros``, and are + are sample devices that demonstrate Rust binding usage and ``qemu_macros``, and are used to further develop them. These two crates are functional\ [#issues]_ replacements for the ``hw/char/pl011.c`` and ``hw/timer/hpet.c`` files. @@ -136,7 +127,7 @@ This section explains how to work with them. Status '''''' -Modules of ``qemu_api`` can be defined as: +The stability of the modules can be defined as: - *complete*: ready for use in new devices; if applicable, the API supports the full functionality available in C @@ -152,26 +143,26 @@ Modules of ``qemu_api`` can be defined as: The status of the modules is as follows: -================ ====================== -module status -================ ====================== -``assertions`` stable -``bitops`` complete -``callbacks`` complete -``cell`` stable -``errno`` complete -``error`` stable -``irq`` complete -``log`` proof of concept -``memory`` stable -``module`` complete -``qdev`` stable -``qom`` stable -``sysbus`` stable -``timer`` stable -``vmstate`` proof of concept -``zeroable`` stable -================ ====================== +========================== ====================== +module status +========================== ====================== +``bql::cell`` stable +``common::assertions`` stable +``common::bitops`` complete +``common::callbacks`` complete +``common::errno`` complete +``common::zeroable`` stable +``hwcore::irq`` complete +``hwcore::qdev`` stable +``hwcore::sysbus`` stable +``migration::vmstate`` stable +``qom`` stable +``system::memory`` stable +``util::error`` stable +``util::log`` proof of concept +``util::module`` complete +``util::timer`` stable +========================== ====================== .. note:: API stability is not a promise, if anything because the C APIs are not a stable @@ -272,7 +263,7 @@ 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. The -``qemu_api::cell`` module provides wrappers that can be used to tell the +``bql::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. @@ -290,7 +281,7 @@ 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)] + #[derive(Debug, common::Wrapper)] pub struct Object(Opaque<bindings::Object>); where the special ``derive`` macro provides useful methods such as @@ -304,7 +295,7 @@ the wrapper to be declared thread-safe:: Writing bindings to C code '''''''''''''''''''''''''' -Here are some things to keep in mind when working on the ``qemu_api`` crate. +Here are some things to keep in mind when working on the QEMU Rust crate. **Look at existing code** Very often, similar idioms in C code correspond to similar tricks in @@ -367,7 +358,7 @@ from the type after ``as`` in the invocation of ``parse_macro_input!``:: .into() } -The ``qemu_api_macros`` crate has utility functions to examine a +The ``qemu_macros`` crate has utility functions to examine a ``DeriveInput`` and perform common checks (e.g. looking for a struct with named fields). These functions return ``Result<..., syn::Error>`` and can be used easily in the procedural macro function:: @@ -408,7 +399,7 @@ Right now, only the nightly version of ``rustfmt`` is supported. This might change in the future. While CI checks for correct formatting via ``cargo fmt --check``, maintainers can fix this for you when applying patches. -It is expected that ``qemu_api`` provides full ``rustdoc`` documentation for +It is expected that QEMU Rust crates provides full ``rustdoc`` documentation for bindings that are in their final shape or close. Adding dependencies diff --git a/docs/devel/tcg-icount.rst b/docs/devel/tcg-icount.rst index 7df883446a..a1dcd79e0f 100644 --- a/docs/devel/tcg-icount.rst +++ b/docs/devel/tcg-icount.rst @@ -37,7 +37,7 @@ translator starts by allocating a budget of instructions to be executed. The budget of instructions is limited by how long it will be until the next timer will expire. We store this budget as part of a vCPU icount_decr field which shared with the machinery for handling -cpu_exit(). The whole field is checked at the start of every +qemu_cpu_kick(). The whole field is checked at the start of every translated block and will cause a return to the outer loop to deal with whatever caused the exit. |