docs/devel/rust.rst

24 However, QEMU's build system also tries to be easy to use for people who
31 * it is also possible to use ``cargo`` for common Rust-specific coding
46 A target for ``rustfmt`` is also declared in ``rust/meson.build``:
88   though hopefully the need for raw pointers will go down over time.
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
95   function; this is an important limitation for QEMU's migration stream
99 * NUL-terminated file names with ``#[track_caller]`` are scheduled for
101   before QEMU can use them.  For now, there is special code in
104 * associated const equality would be nice to have for some users of
120 * ``qemu_api`` for bindings to C code and useful functionality
128   for the ``hw/char/pl011.c`` and ``hw/timer/hpet.c`` files.
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
184 apply to, for example ``timer_mod`` or ``sysbus_connect_irq``.  Furthermore,
194 the hierarchy; for the top class, decide on a case by case basis.
196 For example:
218 is the same for all devices.  Therefore, ``DeviceMethods`` does not
250 These rules can be tested with `MIRI`__, for example.
255 objects are *shared*, for example because they are part of the QOM composition
260 2. a ``*mut`` is created, for example as the opaque value for a ``MemoryRegion``
276 rules for the "Big QEMU Lock".  In the future, similar cell types might
277 also be provided for ``AioContext``-based locking as well.
288 a raw pointer, for use in calls to C functions.  It can be used for
297 then manually check for the big QEMU lock with assertions, which allows
300     unsafe impl Send for Object {}
301     unsafe impl Sync for Object {}
312   ``MemoryRegion``.  Reuse existing patterns for handling lifetimes;
313   for example use ``&T`` for QOM objects that do not need a reference
315   ``Owned<T>`` for those that need it.
322   for the fields of a Rust ``struct``.
332   If you need to settle for an inferior solution because of the currently
339   QEMU lock.  Use ``BqlCell`` and ``BqlRefCell`` for interior data,
345   to isolate any tricks in a place (for example a ``struct``, a trait
356 the latter with the ``_or_error`` suffix.  The code for the latter is more
369 ``DeriveInput`` and perform common checks (e.g. looking for a struct
383 Use procedural macros with care.  They are mostly useful for two purposes:
385 * Performing consistency checks; for example ``#[derive(Object)]`` checks
390   on types and attributes.  For example, ``#[derive(TryInto)]`` builds an
396 "regular" declarative (``macro_rules!``) macros and write unit tests for
406 might change in the future.  While CI checks for correct formatting via
407 ``cargo fmt --check``, maintainers can fix this for you when applying patches.
409 It is expected that ``qemu_api`` provides full ``rustdoc`` documentation for
418 functionality; see for example QEMU's ``assertions`` module.
422 to build them.  While Meson has initial support for parsing ``Cargo.lock``
425 Therefore, external crates must be added as subprojects for Meson to
429 and therefore there is a single lock file for the whole build.
439 first non-zero number.  For example, a crate with version ``0.2.3`` will use
440 ``0.2`` for its ``SEMVER``, while a crate with version ``1.0.84`` will use ``1``.
445 * ``subproject`` and ``dependency`` lines for all dependent crates
453 ``meson.override_dependency`` for dependencies of procedural macros.
473 do a dummy change to the ``.wrap`` file (for example adding a comment like