Lines Matching full:the
6 Rust in QEMU is a project to enable using the Rust programming language
9 Right now, the focus is on making it possible to write devices that inherit
16 Building the Rust in QEMU code
19 The Rust in QEMU code is included in the emulators via Meson. Meson
21 together with the C code. This is completely automatic when you run
25 are accustomed to the more "normal" Cargo-based development workflow.
28 * the set of warnings and lints that are used to build QEMU always
29 comes from the ``rust/Cargo.toml`` workspace file
37 of Cargo will complain that it cannot find the generated sources,
50 * by invoking ``cargo`` through the Meson `development environment`__
61 * by pointing the ``MESON_BUILD_ROOT`` to the top of your QEMU build
63 you can set the environment variable through the
66 As shown above, you can use the ``--tests`` option as usual to operate on test
73 Note that doctests require all ``.o`` files from the build to be available.
78 QEMU supports rustc version 1.77.0 and newer. Notably, the following features
82 associated constants in the ``FnCall`` trait.
88 though hopefully the need for raw pointers will go down over time.
90 * ``new_uninit`` (stable in 1.82.0). This is used internally by the ``pinned_init``
97 it is hard to place the ``VMStateField`` definitions in traits.
128 for the ``hw/char/pl011.c`` and ``hw/timer/hpet.c`` files.
130 .. [#issues] The ``pl011`` crate is synchronized with ``hw/char/pl011.c``
131 as of commit 3e0f118f82. The ``hpet`` crate is synchronized as of
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
150 - *initial*: the API is in its initial stages; it requires large amount of
153 The status of the modules is as follows:
177 API stability is not a promise, if anything because the C APIs are not a stable
184 C function names usually are prefixed according to the data type that they
187 Generally speaking, these are all removed in the corresponding Rust functions:
191 Sometimes however a name appears multiple times in the QOM class hierarchy,
192 and the only difference is in the prefix. An example is ``qdev_realize`` and
194 the hierarchy, always add the prefix to the classes that are lower in
195 the hierarchy; for the top class, decide on a case by case basis.
205 Here, the name is not exactly the same, but nevertheless ``PciDeviceMethods``
206 adds the prefix to avoid confusion, because the functionality of
217 Here, the lower classes do not add any functionality, and mostly
218 provide extra compile-time checking; the basic *realize* functionality
219 is the same for all devices. Therefore, ``DeviceMethods`` does not
220 add the prefix.
222 Whenever a name is unique in the hierarchy, instead, you should
223 always remove the class name prefix.
231 it *cannot* be casted to ``&mut`` unless the value was stored to the ``*mut``
233 shared reference was created between the store to the ``*mut`` and the load::
239 // p_raw keeps the mutable reference "alive"
244 // Bring back the mutable reference, its lifetime overlaps
256 objects are *shared*, for example because they are part of the QOM composition
257 tree. This creates exactly the above scenario:
261 2. a ``*mut`` is created, for example as the opaque value for a ``MemoryRegion``
263 3. the QOM object is placed in the composition tree
265 4. a memory access dereferences the opaque value to a ``&mut``
267 5. but the shared reference is still present in the composition tree
274 to a Rust mutable reference, and use a shared reference instead. The
275 ``qemu_api::cell`` module provides wrappers that can be used to tell the
277 rules for the "Big QEMU Lock". In the future, similar cell types might
280 In particular, device code will usually rely on the ``BqlRefCell`` and
281 ``BqlCell`` type to ensure that data is accessed correctly under the
282 "Big QEMU Lock". These cell types are also known to the ``vmstate``
284 representation of a ``struct``'s layout. Note that the same is not true
287 Bindings code instead will usually use the ``Opaque`` type, which hides
288 the contents of the underlying struct and can be easily converted to
296 where the special ``derive`` macro provides useful methods such as
297 ``from_raw``, ``as_ptr`, ``as_mut_ptr`` and ``raw_get``. The bindings will
298 then manually check for the big QEMU lock with assertions, which allows
299 the wrapper to be declared thread-safe::
307 Here are some things to keep in mind when working on the ``qemu_api`` crate.
311 Rust bindings. If the C code uses ``offsetof``, look at qdev properties
312 or ``vmstate``. If the C code has a complex const struct, look at
318 **Use the type system**
322 The ``vmstate`` module has examples of how to retrieve type information
323 for the fields of a Rust ``struct``.
333 If you need to settle for an inferior solution because of the currently
334 supported set of Rust versions, document it in the source and in this
335 file. This ensures that it can be fixed when the minimum supported
339 When marking a type ``Sync``, be careful of whether it needs the big
348 toy versions of the code in the documentation.
354 returning ``Result<proc_macro2::TokenStream, MacroError>`` with the body of
355 the procedural macro, and the second returning ``proc_macro::TokenStream``
356 which is the actual procedural macro. The former's name is the same as
357 the latter with the ``_or_error`` suffix. The code for the latter is more
358 or less fixed; it follows the following template, which is fixed apart
359 from the type after ``as`` in the invocation of ``parse_macro_input!``::
369 The ``qemu_api_macros`` crate has utility functions to examine a
372 and can be used easily in the procedural macro function::
387 that the structure has ``#[repr[C])`` and that the type of the first field
388 is consistent with the ``ObjectType`` declaration.
392 implementation of ``TryFrom``, and it uses the ``#[repr(...)]`` attribute
393 as the ``TryFrom`` source and error types.
395 Procedural macros can be hard to debug and test; if the code generation
406 Right now, only the nightly version of ``rustfmt`` is supported. This
407 might change in the future. While CI checks for correct formatting via
416 Generally, the set of dependent crates is kept small. Think twice before
418 dependencies itself. Sometimes QEMU only needs a small subset of the
422 slightly complicated process, mostly due to the need to teach Meson how
427 learn how to build them, as well as to the relevant ``Cargo.toml`` files.
428 The versions specified in ``rust/Cargo.lock`` must be the same as the
429 subprojects; note that the ``rust/`` directory forms a Cargo `workspace`__,
430 and therefore there is a single lock file for the whole build.
434 Choose a version of the crate that works with QEMU's minimum supported
437 Second, a new ``wrap`` file must be added to teach Meson how to download the
438 crate. The wrap file must be named ``NAME-SEMVER-rs.wrap``, where ``NAME``
439 is the name of the crate and ``SEMVER`` is the version up to and including the
443 Third, the Meson rules to build the crate must be added at
448 * a ``static_library`` or ``rust.proc_macro`` line to perform the actual build
451 the result to QEMU and to other subprojects
457 non-native versions of the crate.
459 It's important to specify the right compiler options. These include:
461 * the language edition (which can be found in the ``Cargo.toml`` file)
463 * the ``--cfg`` (which have to be "reverse engineered" from the ``build.rs``
464 file of the crate).
469 After every change to the ``meson.build`` file you have to update the patched
471 be automated in the future.
473 Also, after every change to the ``meson.build`` file it is strongly suggested to
474 do a dummy change to the ``.wrap`` file (for example adding a comment like
475 ``# version 2``), which will help Meson notice that the subproject is out of date.
477 As a last step, add the new subproject to ``scripts/archive-source.sh``,