Rust
M: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
S: Maintained
+F: rust/common/
F: rust/qemu-api
F: rust/qemu-api-macros
F: rust/rustfmt.toml
"qemu_api_macros",
]
+[[package]]
+name = "common"
+version = "0.1.0"
+dependencies = [
+ "libc",
+]
+
[[package]]
name = "either"
version = "1.12.0"
name = "hpet"
version = "0.1.0"
dependencies = [
+ "common",
"qemu_api",
"qemu_api_macros",
]
"bilge",
"bilge-impl",
"bits",
+ "common",
"qemu_api",
"qemu_api_macros",
]
version = "0.1.0"
dependencies = [
"anyhow",
+ "common",
"foreign",
"libc",
"qemu_api_macros",
resolver = "2"
members = [
"bits",
+ "common",
"qemu-api-macros",
"qemu-api",
"hw/char/pl011",
--- /dev/null
+[package]
+name = "common"
+version = "0.1.0"
+description = "Rust common code for QEMU"
+resolver = "2"
+publish = false
+
+authors.workspace = true
+edition.workspace = true
+homepage.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+libc.workspace = true
+
+[lints]
+workspace = true
--- /dev/null
+_common_cfg = run_command(rustc_args,
+ '--config-headers', config_host_h, '--features', files('Cargo.toml'),
+ capture: true, check: true).stdout().strip().splitlines()
+
+_common_rs = static_library(
+ 'common',
+ structured_sources(
+ [
+ 'src/lib.rs',
+ 'src/assertions.rs',
+ 'src/bitops.rs',
+ 'src/callbacks.rs',
+ 'src/errno.rs',
+ 'src/opaque.rs',
+ 'src/uninit.rs',
+ 'src/zeroable.rs',
+ ],
+ ),
+ override_options: ['rust_std=2021', 'build.rust_std=2021'],
+ rust_abi: 'rust',
+ rust_args: _common_cfg,
+ dependencies: [libc_rs],
+)
+
+common_rs = declare_dependency(link_with: [_common_rs])
+
+# Doctests are essentially integration tests, so they need the same dependencies.
+# Note that running them requires the object files for C code, so place them
+# in a separate suite that is run by the "build" CI jobs rather than "check".
+rust.doctest('rust-common-doctests',
+ _common_rs,
+ protocol: 'rust',
+ dependencies: common_rs,
+ suite: ['doc', 'rust'])
//! types match the expectations of C code.
//!
//! Documentation is hidden because it only exposes macros, which
-//! are exported directly from `qemu_api`.
+//! are exported directly from `common`.
// Based on https://stackoverflow.com/questions/64251852/x/70978292#70978292
// (stackoverflow answers are released under MIT license).
/// # Examples
///
/// ```
-/// # use qemu_api::assert_same_type;
+/// # use common::assert_same_type;
/// # use std::ops::Deref;
/// assert_same_type!(u32, u32);
/// assert_same_type!(<Box<u32> as Deref>::Target, u32);
/// Different types will cause a compile failure
///
/// ```compile_fail
-/// # use qemu_api::assert_same_type;
+/// # use common::assert_same_type;
/// assert_same_type!(&Box<u32>, &u32);
/// ```
#[macro_export]
/// # Examples
///
/// ```
-/// # use qemu_api::assert_field_type;
+/// # use common::assert_field_type;
/// pub struct A {
/// field1: u32,
/// }
/// Different types will cause a compile failure
///
/// ```compile_fail
-/// # use qemu_api::assert_field_type;
+/// # use common::assert_field_type;
/// # pub struct A { field1: u32 }
/// assert_field_type!(A, field1, i32);
/// ```
/// # Examples
///
/// ```
-/// # use qemu_api::assert_match;
+/// # use common::assert_match;
/// // JoinHandle does not implement `Eq`, therefore the result
/// // does not either.
/// let result: Result<std::thread::JoinHandle<()>, u32> = Err(42);
/// # Examples
///
/// ```
-/// # use qemu_api::static_assert;
+/// # use common::static_assert;
/// static_assert!("abc".len() == 3);
/// ```
///
/// ```compile_fail
-/// # use qemu_api::static_assert;
+/// # use common::static_assert;
/// static_assert!("abc".len() == 2); // does not compile
/// ```
#[macro_export]
// SPDX-License-Identifier: GPL-2.0-or-later
//! This module provides bit operation extensions to integer types.
-//! It is usually included via the `qemu_api` prelude.
use std::ops::{
Add, AddAssign, BitAnd, BitAndAssign, BitOr, BitOrAssign, BitXor, BitXorAssign, Div, DivAssign,
/// # Examples
///
/// ```
-/// # use qemu_api::callbacks::FnCall;
+/// # use common::callbacks::FnCall;
/// fn call_it<F: for<'a> FnCall<(&'a str,), String>>(_f: &F, s: &str) -> String {
/// F::call((s,))
/// }
/// Attempting to pass a non-zero-sized closure causes a compile-time failure:
///
/// ```compile_fail
-/// # use qemu_api::callbacks::FnCall;
+/// # use common::callbacks::FnCall;
/// # fn call_it<'a, F: FnCall<(&'a str,), String>>(_f: &F, s: &'a str) -> String {
/// # F::call((s,))
/// # }
/// `()` can be used to indicate "no function":
///
/// ```
-/// # use qemu_api::callbacks::FnCall;
+/// # use common::callbacks::FnCall;
/// fn optional<F: for<'a> FnCall<(&'a str,), String>>(_f: &F, s: &str) -> Option<String> {
/// if F::IS_SOME {
/// Some(F::call((s,)))
/// Invoking `F::call` will then be a run-time error.
///
/// ```should_panic
-/// # use qemu_api::callbacks::FnCall;
+/// # use common::callbacks::FnCall;
/// # fn call_it<F: for<'a> FnCall<(&'a str,), String>>(_f: &F, s: &str) -> String {
/// # F::call((s,))
/// # }
/// You can use `IS_SOME` to catch this at compile time:
///
/// ```compile_fail
- /// # use qemu_api::callbacks::FnCall;
+ /// # use common::callbacks::FnCall;
/// fn call_it<F: for<'a> FnCall<(&'a str,), String>>(_f: &F, s: &str) -> String {
/// const { assert!(F::IS_SOME) }
/// F::call((s,))
/// are interpreted as negated `errno` and turned into an `Err`.
///
/// ```
-/// # use qemu_api::errno::into_io_result;
+/// # use common::errno::into_io_result;
/// # use std::io::ErrorKind;
/// let ok = into_io_result(1i32).unwrap();
/// assert_eq!(ok, 1u32);
/// likely overflows and will panic:
///
/// ```should_panic
-/// # use qemu_api::errno::into_io_result;
+/// # use common::errno::into_io_result;
/// # #[allow(dead_code)]
/// let err = into_io_result(-0x1234_5678i32); // panic
/// ```
/// values to report errors.
///
/// ```
-/// # use qemu_api::errno::into_neg_errno;
+/// # use common::errno::into_neg_errno;
/// # use std::io::{self, ErrorKind};
/// let ok: io::Result<()> = Ok(());
/// assert_eq!(into_neg_errno(ok), 0);
/// positive:
///
/// ```should_panic
-/// # use qemu_api::errno::into_neg_errno;
+/// # use common::errno::into_neg_errno;
/// # use std::io;
/// let err: io::Result<u32> = Ok(0x8899_AABB);
/// into_neg_errno(err) // panic
--- /dev/null
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+pub mod assertions;
+
+pub mod bitops;
+
+pub mod callbacks;
+pub use callbacks::FnCall;
+
+pub mod errno;
+pub use errno::Errno;
+
+pub mod opaque;
+pub use opaque::{Opaque, Wrapper};
+
+pub mod uninit;
+pub use uninit::MaybeUninitField;
+
+pub mod zeroable;
+pub use zeroable::Zeroable;
--- /dev/null
+// SPDX-License-Identifier: MIT
+
+//! ## Opaque wrappers
+//!
+//! The cell types from the previous section are useful at the boundaries
+//! of code that requires interior mutability. When writing glue code that
+//! interacts directly with C structs, however, it is useful to operate
+//! at a lower level.
+//!
+//! C functions often violate Rust's fundamental assumptions about memory
+//! safety by modifying memory even if it is shared. Furthermore, C structs
+//! often start their life uninitialized and may be populated lazily.
+//!
+//! For this reason, this module provides the [`Opaque<T>`] type to opt out
+//! of Rust's usual guarantees about the wrapped type. Access to the wrapped
+//! value is always through raw pointers, obtained via methods like
+//! [`as_mut_ptr()`](Opaque::as_mut_ptr) and [`as_ptr()`](Opaque::as_ptr). These
+//! pointers can then be passed to C functions or dereferenced; both actions
+//! require `unsafe` blocks, making it clear where safety guarantees must be
+//! manually verified. For example
+//!
+//! ```ignore
+//! unsafe {
+//! let state = Opaque::<MyStruct>::uninit();
+//! qemu_struct_init(state.as_mut_ptr());
+//! }
+//! ```
+//!
+//! [`Opaque<T>`] will usually be wrapped one level further, so that
+//! bridge methods can be added to the wrapper:
+//!
+//! ```ignore
+//! pub struct MyStruct(Opaque<bindings::MyStruct>);
+//!
+//! impl MyStruct {
+//! fn new() -> Pin<Box<MyStruct>> {
+//! let result = Box::pin(unsafe { Opaque::uninit() });
+//! unsafe { qemu_struct_init(result.as_mut_ptr()) };
+//! result
+//! }
+//! }
+//! ```
+//!
+//! This pattern of wrapping bindgen-generated types in [`Opaque<T>`] provides
+//! several advantages:
+//!
+//! * The choice of traits to be implemented is not limited by the
+//! bindgen-generated code. For example, [`Drop`] can be added without
+//! disabling [`Copy`] on the underlying bindgen type
+//!
+//! * [`Send`] and [`Sync`] implementations can be controlled by the wrapper
+//! type rather than being automatically derived from the C struct's layout
+//!
+//! * Methods can be implemented in a separate crate from the bindgen-generated
+//! bindings
+//!
+//! * [`Debug`](std::fmt::Debug) and [`Display`](std::fmt::Display)
+//! implementations can be customized to be more readable than the raw C
+//! struct representation
+//!
+//! The [`Opaque<T>`] type does not include BQL validation; it is possible to
+//! assert in the code that the right lock is taken, to use it together
+//! with a custom lock guard type, or to let C code take the lock, as
+//! appropriate. It is also possible to use it with non-thread-safe
+//! types, since by default (unlike [`BqlCell`] and [`BqlRefCell`]
+//! it is neither `Sync` nor `Send`.
+//!
+//! While [`Opaque<T>`] is necessary for C interop, it should be used sparingly
+//! and only at FFI boundaries. For QEMU-specific types that need interior
+//! mutability, prefer [`BqlCell`] or [`BqlRefCell`].
+//!
+//! [`BqlCell`]: ../../qemu_api/cell/struct.BqlCell.html
+//! [`BqlRefCell`]: ../../qemu_api/cell/struct.BqlRefCell.html
+use std::{cell::UnsafeCell, fmt, marker::PhantomPinned, mem::MaybeUninit, ptr::NonNull};
+
+/// Stores an opaque value that is shared with C code.
+///
+/// Often, C structs can changed when calling a C function even if they are
+/// behind a shared Rust reference, or they can be initialized lazily and have
+/// invalid bit patterns (e.g. `3` for a [`bool`]). This goes against Rust's
+/// strict aliasing rules, which normally prevent mutation through shared
+/// references.
+///
+/// Wrapping the struct with `Opaque<T>` ensures that the Rust compiler does not
+/// assume the usual constraints that Rust structs require, and allows using
+/// shared references on the Rust side.
+///
+/// `Opaque<T>` is `#[repr(transparent)]`, so that it matches the memory layout
+/// of `T`.
+#[repr(transparent)]
+pub struct Opaque<T> {
+ value: UnsafeCell<MaybeUninit<T>>,
+ // PhantomPinned also allows multiple references to the `Opaque<T>`, i.e.
+ // one `&mut Opaque<T>` can coexist with a `&mut T` or any number of `&T`;
+ // see https://docs.rs/pinned-aliasable/latest/pinned_aliasable/.
+ _pin: PhantomPinned,
+}
+
+impl<T> Opaque<T> {
+ /// Creates a new shared reference from a C pointer
+ ///
+ /// # Safety
+ ///
+ /// The pointer must be valid, though it need not point to a valid value.
+ pub unsafe fn from_raw<'a>(ptr: *mut T) -> &'a Self {
+ let ptr = NonNull::new(ptr).unwrap().cast::<Self>();
+ // SAFETY: Self is a transparent wrapper over T
+ unsafe { ptr.as_ref() }
+ }
+
+ /// Creates a new opaque object with uninitialized contents.
+ ///
+ /// # Safety
+ ///
+ /// Ultimately the pointer to the returned value will be dereferenced
+ /// in another `unsafe` block, for example when passing it to a C function,
+ /// but the functions containing the dereference are usually safe. The
+ /// value returned from `uninit()` must be initialized and pinned before
+ /// calling them.
+ pub const unsafe fn uninit() -> Self {
+ Self {
+ value: UnsafeCell::new(MaybeUninit::uninit()),
+ _pin: PhantomPinned,
+ }
+ }
+
+ /// Creates a new opaque object with zeroed contents.
+ ///
+ /// # Safety
+ ///
+ /// Ultimately the pointer to the returned value will be dereferenced
+ /// in another `unsafe` block, for example when passing it to a C function,
+ /// but the functions containing the dereference are usually safe. The
+ /// value returned from `uninit()` must be pinned (and possibly initialized)
+ /// before calling them.
+ pub const unsafe fn zeroed() -> Self {
+ Self {
+ value: UnsafeCell::new(MaybeUninit::zeroed()),
+ _pin: PhantomPinned,
+ }
+ }
+
+ /// Returns a raw mutable pointer to the opaque data.
+ pub const fn as_mut_ptr(&self) -> *mut T {
+ UnsafeCell::get(&self.value).cast()
+ }
+
+ /// Returns a raw pointer to the opaque data.
+ pub const fn as_ptr(&self) -> *const T {
+ self.as_mut_ptr().cast_const()
+ }
+
+ /// Returns a raw pointer to the opaque data that can be passed to a
+ /// C function as `void *`.
+ pub const fn as_void_ptr(&self) -> *mut std::ffi::c_void {
+ UnsafeCell::get(&self.value).cast()
+ }
+
+ /// Converts a raw pointer to the wrapped type.
+ pub const fn raw_get(slot: *mut Self) -> *mut T {
+ // Compare with Linux's raw_get method, which goes through an UnsafeCell
+ // because it takes a *const Self instead.
+ slot.cast()
+ }
+}
+
+impl<T> fmt::Debug for Opaque<T> {
+ fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+ let mut name: String = "Opaque<".to_string();
+ name += std::any::type_name::<T>();
+ name += ">";
+ f.debug_tuple(&name).field(&self.as_ptr()).finish()
+ }
+}
+
+impl<T: Default> Opaque<T> {
+ /// Creates a new opaque object with default contents.
+ ///
+ /// # Safety
+ ///
+ /// Ultimately the pointer to the returned value will be dereferenced
+ /// in another `unsafe` block, for example when passing it to a C function,
+ /// but the functions containing the dereference are usually safe. The
+ /// value returned from `uninit()` must be pinned before calling them.
+ pub unsafe fn new() -> Self {
+ Self {
+ value: UnsafeCell::new(MaybeUninit::new(T::default())),
+ _pin: PhantomPinned,
+ }
+ }
+}
+
+/// Annotates [`Self`] as a transparent wrapper for another type.
+///
+/// Usually defined via the [`qemu_api_macros::Wrapper`] derive macro.
+///
+/// # Examples
+///
+/// ```
+/// # use std::mem::ManuallyDrop;
+/// # use common::opaque::Wrapper;
+/// #[repr(transparent)]
+/// pub struct Example {
+/// inner: ManuallyDrop<String>,
+/// }
+///
+/// unsafe impl Wrapper for Example {
+/// type Wrapped = String;
+/// }
+/// ```
+///
+/// # Safety
+///
+/// `Self` must be a `#[repr(transparent)]` wrapper for the `Wrapped` type,
+/// whether directly or indirectly.
+///
+/// # Methods
+///
+/// By convention, types that implement Wrapper also implement the following
+/// methods:
+///
+/// ```ignore
+/// pub const unsafe fn from_raw<'a>(value: *mut Self::Wrapped) -> &'a Self;
+/// pub const unsafe fn as_mut_ptr(&self) -> *mut Self::Wrapped;
+/// pub const unsafe fn as_ptr(&self) -> *const Self::Wrapped;
+/// pub const unsafe fn raw_get(slot: *mut Self) -> *const Self::Wrapped;
+/// ```
+///
+/// They are not defined here to allow them to be `const`.
+///
+/// [`qemu_api_macros::Wrapper`]: ../../qemu_api_macros/derive.Wrapper.html
+pub unsafe trait Wrapper {
+ type Wrapped;
+}
+
+unsafe impl<T> Wrapper for Opaque<T> {
+ type Wrapped = T;
+}
/// }
///
/// # use std::mem::MaybeUninit;
-/// # use qemu_api::{assert_match, uninit_field_mut};
+/// # use common::{assert_match, uninit_field_mut};
///
/// let mut s: MaybeUninit<S> = MaybeUninit::zeroed();
/// uninit_field_mut!(s, x).write(5);
--- /dev/null
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+//! Defines a trait for structs that can be safely initialized with zero bytes.
+
+/// Encapsulates the requirement that
+/// `MaybeUninit::<Self>::zeroed().assume_init()` does not cause undefined
+/// behavior.
+///
+/// # Safety
+///
+/// Do not add this trait to a type unless all-zeroes is a valid value for the
+/// type. In particular, raw pointers can be zero, but references and
+/// `NonNull<T>` cannot.
+pub unsafe trait Zeroable: Default {
+ /// Return a value of Self whose memory representation consists of all
+ /// zeroes, with the possible exclusion of padding bytes.
+ const ZERO: Self = unsafe { ::core::mem::MaybeUninit::<Self>::zeroed().assume_init() };
+}
bilge = { version = "0.2.0" }
bilge-impl = { version = "0.2.0" }
bits = { path = "../../../bits" }
+common = { path = "../../../common" }
qemu_api = { path = "../../../qemu-api" }
qemu_api_macros = { path = "../../../qemu-api-macros" }
bilge_rs,
bilge_impl_rs,
bits_rs,
- qemu_api,
+ common_rs,
+ qemu_api_rs,
qemu_api_macros,
],
)
use std::{ffi::CStr, mem::size_of};
+use common::{static_assert, uninit_field_mut};
use qemu_api::{
chardev::{CharBackend, Chardev, Event},
impl_vmstate_forward, impl_vmstate_struct,
prelude::*,
qdev::{Clock, ClockEvent, DeviceImpl, DeviceState, ResetType, ResettablePhasesImpl},
qom::{ObjectImpl, Owned, ParentField, ParentInit},
- static_assert,
sysbus::{SysBusDevice, SysBusDeviceImpl},
- uninit_field_mut,
vmstate::{self, VMStateDescription, VMStateDescriptionBuilder},
vmstate_fields, vmstate_of, vmstate_subsections, vmstate_unused,
};
rust-version.workspace = true
[dependencies]
+common = { path = "../../../common" }
qemu_api = { path = "../../../qemu-api" }
qemu_api_macros = { path = "../../../qemu-api-macros" }
override_options: ['rust_std=2021', 'build.rust_std=2021'],
rust_abi: 'rust',
dependencies: [
- qemu_api,
+ common_rs,
+ qemu_api_rs,
qemu_api_macros,
],
)
slice::from_ref,
};
+use common::{bitops::IntegerExt, uninit_field_mut};
use qemu_api::{
bindings::{
address_space_memory, address_space_stl_le, qdev_prop_bit, qdev_prop_bool,
qom_isa,
sysbus::{SysBusDevice, SysBusDeviceImpl},
timer::{Timer, CLOCK_VIRTUAL, NANOSECONDS_PER_SECOND},
- uninit_field_mut,
vmstate::{self, VMStateDescription, VMStateDescriptionBuilder},
vmstate_fields, vmstate_of, vmstate_subsections, vmstate_validate,
};
use std::ptr::addr_of_mut;
-use qemu_api::{cell::bql_locked, zeroable::Zeroable};
+use common::Zeroable;
+use qemu_api::cell::bql_locked;
/// Each `HPETState` represents a Event Timer Block. The v1 spec supports
/// up to 8 blocks. QEMU only uses 1 block (in PC machine).
genrs = []
+subdir('common')
subdir('qemu-api-macros')
subdir('bits')
subdir('qemu-api')
.ident;
Ok(quote! {
- ::qemu_api::assert_field_type!(#name, #parent,
+ ::common::assert_field_type!(#name, #parent,
::qemu_api::qom::ParentField<<#name as ::qemu_api::qom::ObjectImpl>::ParentType>);
::qemu_api::module_init! {
let typ = &field.ty;
Ok(quote! {
- unsafe impl ::qemu_api::cell::Wrapper for #name {
- type Wrapped = <#typ as ::qemu_api::cell::Wrapper>::Wrapped;
+ unsafe impl ::common::opaque::Wrapper for #name {
+ type Wrapped = <#typ as ::common::opaque::Wrapper>::Wrapped;
}
impl #name {
- pub unsafe fn from_raw<'a>(ptr: *mut <Self as ::qemu_api::cell::Wrapper>::Wrapped) -> &'a Self {
+ pub unsafe fn from_raw<'a>(ptr: *mut <Self as ::common::opaque::Wrapper>::Wrapped) -> &'a Self {
let ptr = ::std::ptr::NonNull::new(ptr).unwrap().cast::<Self>();
unsafe { ptr.as_ref() }
}
- pub const fn as_mut_ptr(&self) -> *mut <Self as ::qemu_api::cell::Wrapper>::Wrapped {
+ pub const fn as_mut_ptr(&self) -> *mut <Self as ::common::opaque::Wrapper>::Wrapped {
self.0.as_mut_ptr()
}
- pub const fn as_ptr(&self) -> *const <Self as ::qemu_api::cell::Wrapper>::Wrapped {
+ pub const fn as_ptr(&self) -> *const <Self as ::common::opaque::Wrapper>::Wrapped {
self.0.as_ptr()
}
self.0.as_void_ptr()
}
- pub const fn raw_get(slot: *mut Self) -> *mut <Self as ::qemu_api::cell::Wrapper>::Wrapped {
+ pub const fn raw_get(slot: *mut Self) -> *mut <Self as ::common::opaque::Wrapper>::Wrapped {
slot.cast()
}
}
offset: ::core::mem::offset_of!(#name, #field_name) as isize,
set_default: #set_default,
defval: ::qemu_api::bindings::Property__bindgen_ty_1 { u: #defval as u64 },
- ..::qemu_api::zeroable::Zeroable::ZERO
+ ..::common::Zeroable::ZERO
}
});
}
offset: ::core::mem::offset_of!(DummyState, migrate_clock) as isize,
set_default: true,
defval: ::qemu_api::bindings::Property__bindgen_ty_1 { u: true as u64 },
- ..::qemu_api::zeroable::Zeroable::ZERO
+ ..::common::Zeroable::ZERO
}
];
}
offset: ::core::mem::offset_of!(DummyState, migrate_clock) as isize,
set_default: true,
defval: ::qemu_api::bindings::Property__bindgen_ty_1 { u: true as u64 },
- ..::qemu_api::zeroable::Zeroable::ZERO
+ ..::common::Zeroable::ZERO
}
];
}
}
},
quote! {
- ::qemu_api::assert_field_type!(
+ ::common::assert_field_type!(
Foo,
_unused,
::qemu_api::qom::ParentField<<Foo as ::qemu_api::qom::ObjectImpl>::ParentType>
rust-version.workspace = true
[dependencies]
+common = { path = "../common" }
qemu_api_macros = { path = "../qemu-api-macros" }
anyhow = { workspace = true }
foreign = { workspace = true }
structured_sources(
[
'src/lib.rs',
- 'src/assertions.rs',
'src/bindings.rs',
- 'src/bitops.rs',
- 'src/callbacks.rs',
'src/cell.rs',
'src/chardev.rs',
- 'src/errno.rs',
'src/error.rs',
'src/irq.rs',
'src/log.rs',
'src/qom.rs',
'src/sysbus.rs',
'src/timer.rs',
- 'src/uninit.rs',
'src/vmstate.rs',
- 'src/zeroable.rs',
],
{'.' : _qemu_api_bindings_inc_rs},
),
override_options: ['rust_std=2021', 'build.rust_std=2021'],
rust_abi: 'rust',
rust_args: _qemu_api_cfg,
- dependencies: [anyhow_rs, foreign_rs, libc_rs, qemu_api_macros, qemuutil_rs,
+ dependencies: [anyhow_rs, common_rs, foreign_rs, libc_rs, qemu_api_macros, qemuutil_rs,
qom, hwcore, chardev, migration],
)
rust.test('rust-qemu-api-tests', _qemu_api_rs,
suite: ['unit', 'rust'])
-qemu_api = declare_dependency(link_with: [_qemu_api_rs],
+qemu_api_rs = declare_dependency(link_with: [_qemu_api_rs],
dependencies: [qemu_api_macros, qom, hwcore, chardev, migration])
# Doctests are essentially integration tests, so they need the same dependencies.
rust.doctest('rust-qemu-api-doctests',
_qemu_api_rs,
protocol: 'rust',
- dependencies: qemu_api,
+ dependencies: [qemu_api_rs],
suite: ['doc', 'rust'])
test('rust-qemu-api-integration',
override_options: ['rust_std=2021', 'build.rust_std=2021'],
rust_args: ['--test'],
install: false,
- dependencies: [qemu_api]),
+ dependencies: [common_rs, qemu_api_rs]),
args: [
'--test', '--test-threads', '1',
'--format', 'pretty',
//! `bindgen`-generated declarations.
+use common::Zeroable;
+
#[cfg(MESON)]
include!("bindings.inc.rs");
unsafe impl Send for VMStateInfo {}
unsafe impl Sync for VMStateInfo {}
+
+// bindgen does not derive Default here
+#[allow(clippy::derivable_impls)]
+impl Default for crate::bindings::VMStateFlags {
+ fn default() -> Self {
+ Self(0)
+ }
+}
+
+unsafe impl Zeroable for crate::bindings::Property__bindgen_ty_1 {}
+unsafe impl Zeroable for crate::bindings::Property {}
+unsafe impl Zeroable for crate::bindings::VMStateFlags {}
+unsafe impl Zeroable for crate::bindings::VMStateField {}
+unsafe impl Zeroable for crate::bindings::VMStateDescription {}
+unsafe impl Zeroable for crate::bindings::MemoryRegionOps__bindgen_ty_1 {}
+unsafe impl Zeroable for crate::bindings::MemoryRegionOps__bindgen_ty_2 {}
+unsafe impl Zeroable for crate::bindings::MemoryRegionOps {}
+unsafe impl Zeroable for crate::bindings::MemTxAttrs {}
+unsafe impl Zeroable for crate::bindings::CharBackend {}
//! Multiple immutable borrows are allowed via [`borrow`](BqlRefCell::borrow),
//! or a single mutable borrow via [`borrow_mut`](BqlRefCell::borrow_mut). The
//! thread will panic if these rules are violated or if the BQL is not held.
-//!
-//! ## Opaque wrappers
-//!
-//! The cell types from the previous section are useful at the boundaries
-//! of code that requires interior mutability. When writing glue code that
-//! interacts directly with C structs, however, it is useful to operate
-//! at a lower level.
-//!
-//! C functions often violate Rust's fundamental assumptions about memory
-//! safety by modifying memory even if it is shared. Furthermore, C structs
-//! often start their life uninitialized and may be populated lazily.
-//!
-//! For this reason, this module provides the [`Opaque<T>`] type to opt out
-//! of Rust's usual guarantees about the wrapped type. Access to the wrapped
-//! value is always through raw pointers, obtained via methods like
-//! [`as_mut_ptr()`](Opaque::as_mut_ptr) and [`as_ptr()`](Opaque::as_ptr). These
-//! pointers can then be passed to C functions or dereferenced; both actions
-//! require `unsafe` blocks, making it clear where safety guarantees must be
-//! manually verified. For example
-//!
-//! ```ignore
-//! unsafe {
-//! let state = Opaque::<MyStruct>::uninit();
-//! qemu_struct_init(state.as_mut_ptr());
-//! }
-//! ```
-//!
-//! [`Opaque<T>`] will usually be wrapped one level further, so that
-//! bridge methods can be added to the wrapper:
-//!
-//! ```ignore
-//! pub struct MyStruct(Opaque<bindings::MyStruct>);
-//!
-//! impl MyStruct {
-//! fn new() -> Pin<Box<MyStruct>> {
-//! let result = Box::pin(unsafe { Opaque::uninit() });
-//! unsafe { qemu_struct_init(result.as_mut_ptr()) };
-//! result
-//! }
-//! }
-//! ```
-//!
-//! This pattern of wrapping bindgen-generated types in [`Opaque<T>`] provides
-//! several advantages:
-//!
-//! * The choice of traits to be implemented is not limited by the
-//! bindgen-generated code. For example, [`Drop`] can be added without
-//! disabling [`Copy`] on the underlying bindgen type
-//!
-//! * [`Send`] and [`Sync`] implementations can be controlled by the wrapper
-//! type rather than being automatically derived from the C struct's layout
-//!
-//! * Methods can be implemented in a separate crate from the bindgen-generated
-//! bindings
-//!
-//! * [`Debug`](std::fmt::Debug) and [`Display`](std::fmt::Display)
-//! implementations can be customized to be more readable than the raw C
-//! struct representation
-//!
-//! The [`Opaque<T>`] type does not include BQL validation; it is possible to
-//! assert in the code that the right lock is taken, to use it together
-//! with a custom lock guard type, or to let C code take the lock, as
-//! appropriate. It is also possible to use it with non-thread-safe
-//! types, since by default (unlike [`BqlCell`] and [`BqlRefCell`]
-//! it is neither `Sync` nor `Send`.
-//!
-//! While [`Opaque<T>`] is necessary for C interop, it should be used sparingly
-//! and only at FFI boundaries. For QEMU-specific types that need interior
-//! mutability, prefer [`BqlCell`] or [`BqlRefCell`].
use std::{
cell::{Cell, UnsafeCell},
cmp::Ordering,
fmt,
- marker::{PhantomData, PhantomPinned},
- mem::{self, MaybeUninit},
+ marker::PhantomData,
+ mem,
ops::{Deref, DerefMut},
ptr::NonNull,
};
(**self).fmt(f)
}
}
-
-/// Stores an opaque value that is shared with C code.
-///
-/// Often, C structs can changed when calling a C function even if they are
-/// behind a shared Rust reference, or they can be initialized lazily and have
-/// invalid bit patterns (e.g. `3` for a [`bool`]). This goes against Rust's
-/// strict aliasing rules, which normally prevent mutation through shared
-/// references.
-///
-/// Wrapping the struct with `Opaque<T>` ensures that the Rust compiler does not
-/// assume the usual constraints that Rust structs require, and allows using
-/// shared references on the Rust side.
-///
-/// `Opaque<T>` is `#[repr(transparent)]`, so that it matches the memory layout
-/// of `T`.
-#[repr(transparent)]
-pub struct Opaque<T> {
- value: UnsafeCell<MaybeUninit<T>>,
- // PhantomPinned also allows multiple references to the `Opaque<T>`, i.e.
- // one `&mut Opaque<T>` can coexist with a `&mut T` or any number of `&T`;
- // see https://docs.rs/pinned-aliasable/latest/pinned_aliasable/.
- _pin: PhantomPinned,
-}
-
-impl<T> Opaque<T> {
- /// Creates a new shared reference from a C pointer
- ///
- /// # Safety
- ///
- /// The pointer must be valid, though it need not point to a valid value.
- pub unsafe fn from_raw<'a>(ptr: *mut T) -> &'a Self {
- let ptr = NonNull::new(ptr).unwrap().cast::<Self>();
- // SAFETY: Self is a transparent wrapper over T
- unsafe { ptr.as_ref() }
- }
-
- /// Creates a new opaque object with uninitialized contents.
- ///
- /// # Safety
- ///
- /// Ultimately the pointer to the returned value will be dereferenced
- /// in another `unsafe` block, for example when passing it to a C function,
- /// but the functions containing the dereference are usually safe. The
- /// value returned from `uninit()` must be initialized and pinned before
- /// calling them.
- pub const unsafe fn uninit() -> Self {
- Self {
- value: UnsafeCell::new(MaybeUninit::uninit()),
- _pin: PhantomPinned,
- }
- }
-
- /// Creates a new opaque object with zeroed contents.
- ///
- /// # Safety
- ///
- /// Ultimately the pointer to the returned value will be dereferenced
- /// in another `unsafe` block, for example when passing it to a C function,
- /// but the functions containing the dereference are usually safe. The
- /// value returned from `uninit()` must be pinned (and possibly initialized)
- /// before calling them.
- pub const unsafe fn zeroed() -> Self {
- Self {
- value: UnsafeCell::new(MaybeUninit::zeroed()),
- _pin: PhantomPinned,
- }
- }
-
- /// Returns a raw mutable pointer to the opaque data.
- pub const fn as_mut_ptr(&self) -> *mut T {
- UnsafeCell::get(&self.value).cast()
- }
-
- /// Returns a raw pointer to the opaque data.
- pub const fn as_ptr(&self) -> *const T {
- self.as_mut_ptr().cast_const()
- }
-
- /// Returns a raw pointer to the opaque data that can be passed to a
- /// C function as `void *`.
- pub const fn as_void_ptr(&self) -> *mut std::ffi::c_void {
- UnsafeCell::get(&self.value).cast()
- }
-
- /// Converts a raw pointer to the wrapped type.
- pub const fn raw_get(slot: *mut Self) -> *mut T {
- // Compare with Linux's raw_get method, which goes through an UnsafeCell
- // because it takes a *const Self instead.
- slot.cast()
- }
-}
-
-impl<T> fmt::Debug for Opaque<T> {
- fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
- let mut name: String = "Opaque<".to_string();
- name += std::any::type_name::<T>();
- name += ">";
- f.debug_tuple(&name).field(&self.as_ptr()).finish()
- }
-}
-
-impl<T: Default> Opaque<T> {
- /// Creates a new opaque object with default contents.
- ///
- /// # Safety
- ///
- /// Ultimately the pointer to the returned value will be dereferenced
- /// in another `unsafe` block, for example when passing it to a C function,
- /// but the functions containing the dereference are usually safe. The
- /// value returned from `uninit()` must be pinned before calling them.
- pub unsafe fn new() -> Self {
- Self {
- value: UnsafeCell::new(MaybeUninit::new(T::default())),
- _pin: PhantomPinned,
- }
- }
-}
-
-/// Annotates [`Self`] as a transparent wrapper for another type.
-///
-/// Usually defined via the [`qemu_api_macros::Wrapper`] derive macro.
-///
-/// # Examples
-///
-/// ```
-/// # use std::mem::ManuallyDrop;
-/// # use qemu_api::cell::Wrapper;
-/// #[repr(transparent)]
-/// pub struct Example {
-/// inner: ManuallyDrop<String>,
-/// }
-///
-/// unsafe impl Wrapper for Example {
-/// type Wrapped = String;
-/// }
-/// ```
-///
-/// # Safety
-///
-/// `Self` must be a `#[repr(transparent)]` wrapper for the `Wrapped` type,
-/// whether directly or indirectly.
-///
-/// # Methods
-///
-/// By convention, types that implement Wrapper also implement the following
-/// methods:
-///
-/// ```ignore
-/// pub const unsafe fn from_raw<'a>(value: *mut Self::Wrapped) -> &'a Self;
-/// pub const unsafe fn as_mut_ptr(&self) -> *mut Self::Wrapped;
-/// pub const unsafe fn as_ptr(&self) -> *const Self::Wrapped;
-/// pub const unsafe fn raw_get(slot: *mut Self) -> *const Self::Wrapped;
-/// ```
-///
-/// They are not defined here to allow them to be `const`.
-pub unsafe trait Wrapper {
- type Wrapped;
-}
-
-unsafe impl<T> Wrapper for Opaque<T> {
- type Wrapped = T;
-}
slice,
};
+use common::{callbacks::FnCall, errno, Opaque};
+
use crate::{
bindings,
- callbacks::FnCall,
- cell::{BqlRefMut, Opaque},
+ cell::{BqlRefCell, BqlRefMut},
prelude::*,
};
use std::ffi::CStr;
use anyhow::anyhow;
+ use common::assert_match;
use foreign::OwnedPointer;
use super::*;
- use crate::{assert_match, bindings};
+ use crate::bindings;
#[track_caller]
fn error_for_test(msg: &CStr) -> OwnedPointer<Error> {
ptr,
};
+use common::Opaque;
+
use crate::{
bindings::{self, qemu_set_irq},
- cell::Opaque,
prelude::*,
qom::ObjectClass,
};
#[rustfmt::skip]
pub mod prelude;
-pub mod assertions;
-pub mod bitops;
-pub mod callbacks;
pub mod cell;
pub mod chardev;
-pub mod errno;
pub mod error;
pub mod irq;
pub mod log;
pub mod qom;
pub mod sysbus;
pub mod timer;
-pub mod uninit;
pub mod vmstate;
-pub mod zeroable;
// Allow proc-macros to refer to `::qemu_api` inside the `qemu_api` crate (this
// crate).
ptr::NonNull,
};
-use crate::{bindings, errno};
+use common::errno;
+
+use crate::bindings;
#[repr(u32)]
/// Represents specific error categories within QEMU's logging system.
};
pub use bindings::{hwaddr, MemTxAttrs};
+use common::{callbacks::FnCall, uninit::MaybeUninitField, zeroable::Zeroable, Opaque};
use crate::{
bindings::{self, device_endian, memory_region_init_io},
- callbacks::FnCall,
- cell::Opaque,
prelude::*,
- uninit::MaybeUninitField,
- zeroable::Zeroable,
};
pub struct MemoryRegionOps<T>(
//! Commonly used traits and types for QEMU.
-pub use crate::bitops::IntegerExt;
-
pub use crate::cell::BqlCell;
pub use crate::cell::BqlRefCell;
-pub use crate::errno;
-
pub use crate::log_mask_ln;
pub use crate::qdev::DeviceMethods;
pub use crate::qom::IsA;
pub use crate::qom::Object;
pub use crate::qom::ObjectCast;
-pub use crate::qom::ObjectDeref;
pub use crate::qom::ObjectClassMethods;
+pub use crate::qom::ObjectDeref;
pub use crate::qom::ObjectMethods;
pub use crate::qom::ObjectType;
};
pub use bindings::{ClockEvent, DeviceClass, Property, ResetType};
+use common::{callbacks::FnCall, Opaque};
use crate::{
bindings::{self, qdev_init_gpio_in, qdev_init_gpio_out, ResettableClass},
- callbacks::FnCall,
- cell::{bql_locked, Opaque},
+ cell::bql_locked,
chardev::Chardev,
error::{Error, Result},
impl_vmstate_c_struct,
bitnr: $bitnr,
set_default: true,
defval: $crate::bindings::Property__bindgen_ty_1 { u: $defval as u64 },
- ..$crate::zeroable::Zeroable::ZERO
+ ..::common::zeroable::Zeroable::ZERO
}
};
($name:expr, $state:ty, $field:ident, $prop:expr, $type:ty, default = $defval:expr$(,)*) => {
offset: ::std::mem::offset_of!($state, $field) as isize,
set_default: true,
defval: $crate::bindings::Property__bindgen_ty_1 { u: $defval as u64 },
- ..$crate::zeroable::Zeroable::ZERO
+ ..::common::zeroable::Zeroable::ZERO
}
};
($name:expr, $state:ty, $field:ident, $prop:expr, $type:ty$(,)*) => {
info: $prop,
offset: ::std::mem::offset_of!($state, $field) as isize,
set_default: false,
- ..$crate::zeroable::Zeroable::ZERO
+ ..::common::zeroable::Zeroable::ZERO
}
};
}
};
pub use bindings::ObjectClass;
+use common::Opaque;
use crate::{
bindings::{
self, object_class_dynamic_cast, object_dynamic_cast, object_get_class,
object_get_typename, object_new, object_ref, object_unref, TypeInfo,
},
- cell::{bql_locked, Opaque},
+ cell::bql_locked,
impl_vmstate_pointer,
};
use std::{ffi::CStr, ptr::addr_of_mut};
pub use bindings::SysBusDeviceClass;
+use common::Opaque;
use crate::{
bindings,
- cell::{bql_locked, Opaque},
+ cell::bql_locked,
irq::{IRQState, InterruptSource},
memory::MemoryRegion,
prelude::*,
pin::Pin,
};
-use crate::{
- bindings::{self, qemu_clock_get_ns, timer_del, timer_init_full, timer_mod, QEMUClockType},
- callbacks::FnCall,
- cell::Opaque,
+use common::{callbacks::FnCall, Opaque};
+
+use crate::bindings::{
+ self, qemu_clock_get_ns, timer_del, timer_init_full, timer_mod, QEMUClockType,
};
/// A safe wrapper around [`bindings::QEMUTimer`].
ptr::{addr_of, NonNull},
};
-pub use crate::bindings::{MigrationPriority, VMStateField};
-use crate::{
- bindings::{self, VMStateFlags},
+use common::{
callbacks::FnCall,
errno::{into_neg_errno, Errno},
- zeroable::Zeroable,
+ Zeroable,
};
+use crate::bindings::{self, VMStateFlags};
+pub use crate::bindings::{MigrationPriority, VMStateField};
+
/// This macro is used to call a function with a generic argument bound
/// to the type of a field. The function must take a
/// [`PhantomData`]`<T>` argument; `T` is the type of
impl_vmstate_transparent!(std::cell::Cell<T> where T: VMState);
impl_vmstate_transparent!(std::cell::UnsafeCell<T> where T: VMState);
impl_vmstate_transparent!(std::pin::Pin<T> where T: VMState);
-impl_vmstate_transparent!(crate::cell::Opaque<T> where T: VMState);
+impl_vmstate_transparent!(::common::Opaque<T> where T: VMState);
#[macro_export]
macro_rules! impl_vmstate_bitsized {
vmsd: ::std::ptr::addr_of!($vmsd),
size: ::std::mem::size_of::<$type>(),
flags: $crate::bindings::VMStateFlags::VMS_STRUCT,
- ..$crate::zeroable::Zeroable::ZERO
+ ..common::zeroable::Zeroable::ZERO
};
}
};
size: $size,
info: unsafe { ::core::ptr::addr_of!($crate::bindings::vmstate_info_unused_buffer) },
flags: $crate::bindings::VMStateFlags::VMS_BUFFER,
- ..$crate::zeroable::Zeroable::ZERO
+ ..::common::Zeroable::ZERO
}
}};
}
#[macro_export]
macro_rules! vmstate_exist_fn {
($struct_name:ty, $test_fn:expr) => {{
- const fn test_cb_builder__<T, F: for<'a> $crate::callbacks::FnCall<(&'a T, u8), bool>>(
+ const fn test_cb_builder__<T, F: for<'a> ::common::callbacks::FnCall<(&'a T, u8), bool>>(
_phantom: ::core::marker::PhantomData<F>,
) -> $crate::vmstate::VMSFieldExistCb {
const { assert!(F::IS_SOME) };
$($field),*,
$crate::bindings::VMStateField {
flags: $crate::bindings::VMStateFlags::VMS_END,
- ..$crate::zeroable::Zeroable::ZERO
+ ..::common::zeroable::Zeroable::ZERO
}
];
_FIELDS.as_ptr()
| $crate::bindings::VMStateFlags::VMS_ARRAY.0,
),
num: 0, // 0 elements: no data, only run test_fn callback
- ..$crate::zeroable::Zeroable::ZERO
+ ..::common::zeroable::Zeroable::ZERO
}
};
}
vmsd: ::core::ptr::addr_of!(*VMSD),
size: ::core::mem::size_of::<$type>(),
flags: $crate::bindings::VMStateFlags::VMS_STRUCT,
- ..$crate::zeroable::Zeroable::ZERO
+ ..common::Zeroable::ZERO
}
};
}
+++ /dev/null
-// SPDX-License-Identifier: GPL-2.0-or-later
-
-//! Defines a trait for structs that can be safely initialized with zero bytes.
-
-/// Encapsulates the requirement that
-/// `MaybeUninit::<Self>::zeroed().assume_init()` does not cause undefined
-/// behavior.
-///
-/// # Safety
-///
-/// Do not add this trait to a type unless all-zeroes is a valid value for the
-/// type. In particular, raw pointers can be zero, but references and
-/// `NonNull<T>` cannot.
-pub unsafe trait Zeroable: Default {
- /// Return a value of Self whose memory representation consists of all
- /// zeroes, with the possible exclusion of padding bytes.
- const ZERO: Self = unsafe { ::core::mem::MaybeUninit::<Self>::zeroed().assume_init() };
-}
-
-// bindgen does not derive Default here
-#[allow(clippy::derivable_impls)]
-impl Default for crate::bindings::VMStateFlags {
- fn default() -> Self {
- Self(0)
- }
-}
-
-unsafe impl Zeroable for crate::bindings::Property__bindgen_ty_1 {}
-unsafe impl Zeroable for crate::bindings::Property {}
-unsafe impl Zeroable for crate::bindings::VMStateFlags {}
-unsafe impl Zeroable for crate::bindings::VMStateField {}
-unsafe impl Zeroable for crate::bindings::VMStateDescription {}
-unsafe impl Zeroable for crate::bindings::MemoryRegionOps__bindgen_ty_1 {}
-unsafe impl Zeroable for crate::bindings::MemoryRegionOps__bindgen_ty_2 {}
-unsafe impl Zeroable for crate::bindings::MemoryRegionOps {}
-unsafe impl Zeroable for crate::bindings::MemTxAttrs {}
-unsafe impl Zeroable for crate::bindings::CharBackend {}
slice,
};
+use common::Opaque;
use qemu_api::{
bindings::{
vmstate_info_bool, vmstate_info_int32, vmstate_info_int64, vmstate_info_int8,
vmstate_info_uint64, vmstate_info_uint8, vmstate_info_unused_buffer, VMStateFlags,
},
- cell::{BqlCell, Opaque},
+ cell::BqlCell,
impl_vmstate_forward, impl_vmstate_struct,
vmstate::{VMStateDescription, VMStateDescriptionBuilder, VMStateField},
vmstate_fields, vmstate_of, vmstate_unused, vmstate_validate,
projects / thirdparty / qemu.git / commitdiff
