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
16 Building the Rust in QEMU code
19 The Rust in QEMU code is included in the emulators via Meson.  Meson
26 In particular:
32   tasks, in particular to invoke ``clippy``, ``rustfmt`` and ``rustdoc``.
35 generated sources from QEMU's build directory and puts it in Cargo's
38 which can be fixed in different ways:
46 A target for ``rustfmt`` is also declared in ``rust/meson.build``:
81 * inline const expression (stable in 1.79.0), currently worked around with
82   associated constants in the ``FnCall`` trait.
84 * associated constants have to be explicitly marked ``'static`` (`changed in
87 * ``&raw`` (stable in 1.82.0).  Use ``addr_of!`` and ``addr_of_mut!`` instead,
90 * ``new_uninit`` (stable in 1.82.0).  This is used internally by the ``pinned_init``
91   crate, which is planned for inclusion in QEMU, but it can be easily patched
94 * referencing statics in constants (stable in 1.83.0).  For now use a const
97   it is hard to place the ``VMStateField`` definitions in traits.
101   before QEMU can use them.  For now, there is special code in
115 Writing Rust code in QEMU
141 - *complete*: ready for use in new devices; if applicable, the API supports the
142   full functionality available in C
150 - *initial*: the API is in its initial stages; it requires large amount of
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
193 ``sysbus_realize``.  In such cases, whenever a name is not unique in
194 the hierarchy, always add the prefix to the classes that are lower in
209 In this case, however, no prefix is needed:
222 Whenever a name is unique in the hierarchy, instead, you should
230 In particular, even if a value is loaded from a raw mutable pointer (``*mut``),
255 Almost all Rust code in QEMU will involve QOM objects, and pointers to these
263 3. the QOM object is placed in the composition tree
267 5. but the shared reference is still present in the composition tree
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
283 crate, which is able to "look inside" them when building an in-memory
289 a raw pointer, for use in calls to C functions.  It can be used for
307 Here are some things to keep in mind when working on the ``qemu_api`` crate.
310   Very often, similar idioms in C code correspond to similar tricks in
315   count (including those that can be embedded in other objects) and
320   (either a builtin one or a user-defined one) in order to pass it to C
321   functions.  Put them in a trait and access it through generic parameters.
328   by generic functions.  C code usually places metadata in global variables;
329   in Rust, they can be stored in traits and then turned into ``static``
334   supported set of Rust versions, document it in the source and in this
338 **Keep locking in mind**.
346   to isolate any tricks in a place (for example a ``struct``, a trait
348   toy versions of the code in the documentation.
353 By conventions, procedural macros are split in two functions, one
359 from the type after ``as`` in the invocation of ``parse_macro_input!``::
372 and can be used easily in the procedural macro function::
407 might change in the future.  While CI checks for correct formatting via
411 bindings that are in their final shape or close.
428 The versions specified in ``rust/Cargo.lock`` must be the same as the
455 If a crate is needed in both procedural macros and QEMU binaries, everything
461 * the language edition (which can be found in the ``Cargo.toml`` file)
471 be automated in the future.