use qemu_api::{
bindings::{self, *},
c_str,
- definitions::ObjectImpl,
- device_class::DeviceImpl,
irq::InterruptSource,
prelude::*,
+ qdev::DeviceImpl,
+ qom::ObjectImpl,
};
use crate::{
let expanded = quote! {
::qemu_api::module_init! {
MODULE_INIT_QOM => unsafe {
- ::qemu_api::bindings::type_register_static(&<#name as ::qemu_api::definitions::ObjectImpl>::TYPE_INFO);
+ ::qemu_api::bindings::type_register_static(&<#name as ::qemu_api::qom::ObjectImpl>::TYPE_INFO);
}
}
};
'src/bitops.rs',
'src/cell.rs',
'src/c_str.rs',
- 'src/definitions.rs',
- 'src/device_class.rs',
'src/irq.rs',
+ 'src/module.rs',
'src/offset_of.rs',
'src/prelude.rs',
+ 'src/qdev.rs',
+ 'src/qom.rs',
'src/sysbus.rs',
'src/vmstate.rs',
'src/zeroable.rs',
+++ /dev/null
-// Copyright 2024, Linaro Limited
-// Author(s): Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
-// SPDX-License-Identifier: GPL-2.0-or-later
-
-//! Definitions required by QEMU when registering a device.
-
-use std::{ffi::CStr, os::raw::c_void};
-
-use crate::bindings::{self, Object, ObjectClass, TypeInfo};
-
-unsafe extern "C" fn rust_instance_init<T: ObjectImpl>(obj: *mut Object) {
- // SAFETY: obj is an instance of T, since rust_instance_init<T>
- // is called from QOM core as the instance_init function
- // for class T
- unsafe { T::INSTANCE_INIT.unwrap()(&mut *obj.cast::<T>()) }
-}
-
-unsafe extern "C" fn rust_instance_post_init<T: ObjectImpl>(obj: *mut Object) {
- // SAFETY: obj is an instance of T, since rust_instance_post_init<T>
- // is called from QOM core as the instance_post_init function
- // for class T
- //
- // FIXME: it's not really guaranteed that there are no backpointers to
- // obj; it's quite possible that they have been created by instance_init().
- // The receiver should be &self, not &mut self.
- T::INSTANCE_POST_INIT.unwrap()(unsafe { &mut *obj.cast::<T>() })
-}
-
-unsafe extern "C" fn rust_class_init<T: ObjectType + ClassInitImpl<T::Class>>(
- klass: *mut ObjectClass,
- _data: *mut c_void,
-) {
- // SAFETY: klass is a T::Class, since rust_class_init<T>
- // is called from QOM core as the class_init function
- // for class T
- T::class_init(unsafe { &mut *klass.cast::<T::Class>() })
-}
-
-/// Trait exposed by all structs corresponding to QOM objects.
-///
-/// # Safety
-///
-/// For classes declared in C:
-///
-/// - `Class` and `TYPE` must match the data in the `TypeInfo`;
-///
-/// - the first field of the struct must be of the instance type corresponding
-/// to the superclass, as declared in the `TypeInfo`
-///
-/// - likewise, the first field of the `Class` struct must be of the class type
-/// corresponding to the superclass
-///
-/// For classes declared in Rust and implementing [`ObjectImpl`]:
-///
-/// - the struct must be `#[repr(C)]`;
-///
-/// - the first field of the struct must be of the instance struct corresponding
-/// to the superclass, which is `ObjectImpl::ParentType`
-///
-/// - likewise, the first field of the `Class` must be of the class struct
-/// corresponding to the superclass, which is `ObjectImpl::ParentType::Class`.
-pub unsafe trait ObjectType: Sized {
- /// The QOM class object corresponding to this struct. This is used
- /// to automatically generate a `class_init` method.
- type Class;
-
- /// The name of the type, which can be passed to `object_new()` to
- /// generate an instance of this type.
- const TYPE_NAME: &'static CStr;
-}
-
-/// Trait a type must implement to be registered with QEMU.
-pub trait ObjectImpl: ObjectType + ClassInitImpl<Self::Class> {
- /// The parent of the type. This should match the first field of
- /// the struct that implements `ObjectImpl`:
- type ParentType: ObjectType;
-
- /// Whether the object can be instantiated
- const ABSTRACT: bool = false;
- const INSTANCE_FINALIZE: Option<unsafe extern "C" fn(obj: *mut Object)> = None;
-
- /// Function that is called to initialize an object. The parent class will
- /// have already been initialized so the type is only responsible for
- /// initializing its own members.
- ///
- /// FIXME: The argument is not really a valid reference. `&mut
- /// MaybeUninit<Self>` would be a better description.
- const INSTANCE_INIT: Option<unsafe fn(&mut Self)> = None;
-
- /// Function that is called to finish initialization of an object, once
- /// `INSTANCE_INIT` functions have been called.
- const INSTANCE_POST_INIT: Option<fn(&mut Self)> = None;
-
- /// Called on descendent classes after all parent class initialization
- /// has occurred, but before the class itself is initialized. This
- /// is only useful if a class is not a leaf, and can be used to undo
- /// the effects of copying the contents of the parent's class struct
- /// to the descendants.
- const CLASS_BASE_INIT: Option<
- unsafe extern "C" fn(klass: *mut ObjectClass, data: *mut c_void),
- > = None;
-
- const TYPE_INFO: TypeInfo = TypeInfo {
- name: Self::TYPE_NAME.as_ptr(),
- parent: Self::ParentType::TYPE_NAME.as_ptr(),
- instance_size: core::mem::size_of::<Self>(),
- instance_align: core::mem::align_of::<Self>(),
- instance_init: match Self::INSTANCE_INIT {
- None => None,
- Some(_) => Some(rust_instance_init::<Self>),
- },
- instance_post_init: match Self::INSTANCE_POST_INIT {
- None => None,
- Some(_) => Some(rust_instance_post_init::<Self>),
- },
- instance_finalize: Self::INSTANCE_FINALIZE,
- abstract_: Self::ABSTRACT,
- class_size: core::mem::size_of::<Self::Class>(),
- class_init: Some(rust_class_init::<Self>),
- class_base_init: Self::CLASS_BASE_INIT,
- class_data: core::ptr::null_mut(),
- interfaces: core::ptr::null_mut(),
- };
-
- // methods on ObjectClass
- const UNPARENT: Option<fn(&Self)> = None;
-}
-
-/// Internal trait used to automatically fill in a class struct.
-///
-/// Each QOM class that has virtual methods describes them in a
-/// _class struct_. Class structs include a parent field corresponding
-/// to the vtable of the parent class, all the way up to [`ObjectClass`].
-/// Each QOM type has one such class struct; this trait takes care of
-/// initializing the `T` part of the class struct, for the type that
-/// implements the trait.
-///
-/// Each struct will implement this trait with `T` equal to each
-/// superclass. For example, a device should implement at least
-/// `ClassInitImpl<`[`DeviceClass`](crate::bindings::DeviceClass)`>` and
-/// `ClassInitImpl<`[`ObjectClass`](crate::bindings::ObjectClass)`>`.
-/// Such implementations are made in one of two ways.
-///
-/// For most superclasses, `ClassInitImpl` is provided by the `qemu-api`
-/// crate itself. The Rust implementation of methods will come from a
-/// trait like [`ObjectImpl`] or
-/// [`DeviceImpl`](crate::device_class::DeviceImpl), and `ClassInitImpl` is
-/// provided by blanket implementations that operate on all implementors of the
-/// `*Impl`* trait. For example:
-///
-/// ```ignore
-/// impl<T> ClassInitImpl<DeviceClass> for T
-/// where
-/// T: ClassInitImpl<ObjectClass> + DeviceImpl,
-/// ```
-///
-/// The bound on `ClassInitImpl<ObjectClass>` is needed so that,
-/// after initializing the `DeviceClass` part of the class struct,
-/// the parent [`ObjectClass`] is initialized as well.
-///
-/// The other case is when manual implementation of the trait is needed.
-/// This covers the following cases:
-///
-/// * if a class implements a QOM interface, the Rust code _has_ to define its
-/// own class struct `FooClass` and implement `ClassInitImpl<FooClass>`.
-/// `ClassInitImpl<FooClass>`'s `class_init` method will then forward to
-/// multiple other `class_init`s, for the interfaces as well as the
-/// superclass. (Note that there is no Rust example yet for using interfaces).
-///
-/// * for classes implemented outside the ``qemu-api`` crate, it's not possible
-/// to add blanket implementations like the above one, due to orphan rules. In
-/// that case, the easiest solution is to implement
-/// `ClassInitImpl<YourSuperclass>` for each subclass and not have a
-/// `YourSuperclassImpl` trait at all.
-///
-/// ```ignore
-/// impl ClassInitImpl<YourSuperclass> for YourSubclass {
-/// fn class_init(klass: &mut YourSuperclass) {
-/// klass.some_method = Some(Self::some_method);
-/// <Self as ClassInitImpl<SysBusDeviceClass>>::class_init(&mut klass.parent_class);
-/// }
-/// }
-/// ```
-///
-/// While this method incurs a small amount of code duplication,
-/// it is generally limited to the recursive call on the last line.
-/// This is because classes defined in Rust do not need the same
-/// glue code that is needed when the classes are defined in C code.
-/// You may consider using a macro if you have many subclasses.
-pub trait ClassInitImpl<T> {
- /// Initialize `klass` to point to the virtual method implementations
- /// for `Self`. On entry, the virtual method pointers are set to
- /// the default values coming from the parent classes; the function
- /// can change them to override virtual methods of a parent class.
- ///
- /// The virtual method implementations usually come from another
- /// trait, for example [`DeviceImpl`](crate::device_class::DeviceImpl)
- /// when `T` is [`DeviceClass`](crate::bindings::DeviceClass).
- ///
- /// On entry, `klass`'s parent class is initialized, while the other fields
- /// are all zero; it is therefore assumed that all fields in `T` can be
- /// zeroed, otherwise it would not be possible to provide the class as a
- /// `&mut T`. TODO: add a bound of [`Zeroable`](crate::zeroable::Zeroable)
- /// to T; this is more easily done once Zeroable does not require a manual
- /// implementation (Rust 1.75.0).
- fn class_init(klass: &mut T);
-}
-
-#[macro_export]
-macro_rules! module_init {
- ($type:ident => $body:block) => {
- const _: () = {
- #[used]
- #[cfg_attr(
- not(any(target_vendor = "apple", target_os = "windows")),
- link_section = ".init_array"
- )]
- #[cfg_attr(target_vendor = "apple", link_section = "__DATA,__mod_init_func")]
- #[cfg_attr(target_os = "windows", link_section = ".CRT$XCU")]
- pub static LOAD_MODULE: extern "C" fn() = {
- extern "C" fn init_fn() {
- $body
- }
-
- extern "C" fn ctor_fn() {
- unsafe {
- $crate::bindings::register_module_init(
- Some(init_fn),
- $crate::bindings::module_init_type::$type,
- );
- }
- }
-
- ctor_fn
- };
- };
- };
-
- // shortcut because it's quite common that $body needs unsafe {}
- ($type:ident => unsafe $body:block) => {
- $crate::module_init! {
- $type => { unsafe { $body } }
- }
- };
-}
-
-/// # Safety
-///
-/// We expect the FFI user of this function to pass a valid pointer that
-/// can be downcasted to type `T`. We also expect the device is
-/// readable/writeable from one thread at any time.
-unsafe extern "C" fn rust_unparent_fn<T: ObjectImpl>(dev: *mut Object) {
- unsafe {
- assert!(!dev.is_null());
- let state = core::ptr::NonNull::new_unchecked(dev.cast::<T>());
- T::UNPARENT.unwrap()(state.as_ref());
- }
-}
-
-impl<T> ClassInitImpl<ObjectClass> for T
-where
- T: ObjectImpl,
-{
- fn class_init(oc: &mut ObjectClass) {
- if <T as ObjectImpl>::UNPARENT.is_some() {
- oc.unparent = Some(rust_unparent_fn::<T>);
- }
- }
-}
-
-unsafe impl ObjectType for Object {
- type Class = ObjectClass;
- const TYPE_NAME: &'static CStr =
- unsafe { CStr::from_bytes_with_nul_unchecked(bindings::TYPE_OBJECT) };
-}
+++ /dev/null
-// Copyright 2024, Linaro Limited
-// Author(s): Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
-// SPDX-License-Identifier: GPL-2.0-or-later
-
-use std::ffi::CStr;
-
-use crate::{
- bindings::{self, DeviceClass, DeviceState, Error, ObjectClass, Property, VMStateDescription},
- definitions::ClassInitImpl,
- prelude::*,
-};
-
-/// Trait providing the contents of [`DeviceClass`].
-pub trait DeviceImpl {
- /// _Realization_ is the second stage of device creation. It contains
- /// all operations that depend on device properties and can fail (note:
- /// this is not yet supported for Rust devices).
- ///
- /// If not `None`, the parent class's `realize` method is overridden
- /// with the function pointed to by `REALIZE`.
- const REALIZE: Option<fn(&mut Self)> = None;
-
- /// If not `None`, the parent class's `reset` method is overridden
- /// with the function pointed to by `RESET`.
- ///
- /// Rust does not yet support the three-phase reset protocol; this is
- /// usually okay for leaf classes.
- const RESET: Option<fn(&mut Self)> = None;
-
- /// An array providing the properties that the user can set on the
- /// device. Not a `const` because referencing statics in constants
- /// is unstable until Rust 1.83.0.
- fn properties() -> &'static [Property] {
- &[]
- }
-
- /// A `VMStateDescription` providing the migration format for the device
- /// Not a `const` because referencing statics in constants is unstable
- /// until Rust 1.83.0.
- fn vmsd() -> Option<&'static VMStateDescription> {
- None
- }
-}
-
-/// # Safety
-///
-/// This function is only called through the QOM machinery and
-/// used by the `ClassInitImpl<DeviceClass>` trait.
-/// We expect the FFI user of this function to pass a valid pointer that
-/// can be downcasted to type `T`. We also expect the device is
-/// readable/writeable from one thread at any time.
-unsafe extern "C" fn rust_realize_fn<T: DeviceImpl>(dev: *mut DeviceState, _errp: *mut *mut Error) {
- assert!(!dev.is_null());
- let state = dev.cast::<T>();
- T::REALIZE.unwrap()(unsafe { &mut *state });
-}
-
-/// # Safety
-///
-/// We expect the FFI user of this function to pass a valid pointer that
-/// can be downcasted to type `T`. We also expect the device is
-/// readable/writeable from one thread at any time.
-unsafe extern "C" fn rust_reset_fn<T: DeviceImpl>(dev: *mut DeviceState) {
- assert!(!dev.is_null());
- let state = dev.cast::<T>();
- T::RESET.unwrap()(unsafe { &mut *state });
-}
-
-impl<T> ClassInitImpl<DeviceClass> for T
-where
- T: ClassInitImpl<ObjectClass> + DeviceImpl,
-{
- fn class_init(dc: &mut DeviceClass) {
- if <T as DeviceImpl>::REALIZE.is_some() {
- dc.realize = Some(rust_realize_fn::<T>);
- }
- if <T as DeviceImpl>::RESET.is_some() {
- unsafe {
- bindings::device_class_set_legacy_reset(dc, Some(rust_reset_fn::<T>));
- }
- }
- if let Some(vmsd) = <T as DeviceImpl>::vmsd() {
- dc.vmsd = vmsd;
- }
- let prop = <T as DeviceImpl>::properties();
- if !prop.is_empty() {
- unsafe {
- bindings::device_class_set_props_n(dc, prop.as_ptr(), prop.len());
- }
- }
-
- <T as ClassInitImpl<ObjectClass>>::class_init(&mut dc.parent_class);
- }
-}
-
-#[macro_export]
-macro_rules! define_property {
- ($name:expr, $state:ty, $field:ident, $prop:expr, $type:ty, default = $defval:expr$(,)*) => {
- $crate::bindings::Property {
- // use associated function syntax for type checking
- name: ::std::ffi::CStr::as_ptr($name),
- info: $prop,
- offset: $crate::offset_of!($state, $field) as isize,
- set_default: true,
- defval: $crate::bindings::Property__bindgen_ty_1 { u: $defval as u64 },
- ..$crate::zeroable::Zeroable::ZERO
- }
- };
- ($name:expr, $state:ty, $field:ident, $prop:expr, $type:ty$(,)*) => {
- $crate::bindings::Property {
- // use associated function syntax for type checking
- name: ::std::ffi::CStr::as_ptr($name),
- info: $prop,
- offset: $crate::offset_of!($state, $field) as isize,
- set_default: false,
- ..$crate::zeroable::Zeroable::ZERO
- }
- };
-}
-
-#[macro_export]
-macro_rules! declare_properties {
- ($ident:ident, $($prop:expr),*$(,)*) => {
- pub static $ident: [$crate::bindings::Property; {
- let mut len = 0;
- $({
- _ = stringify!($prop);
- len += 1;
- })*
- len
- }] = [
- $($prop),*,
- ];
- };
-}
-
-unsafe impl ObjectType for DeviceState {
- type Class = DeviceClass;
- const TYPE_NAME: &'static CStr =
- unsafe { CStr::from_bytes_with_nul_unchecked(bindings::TYPE_DEVICE) };
-}
pub mod bitops;
pub mod c_str;
pub mod cell;
-pub mod definitions;
-pub mod device_class;
pub mod irq;
+pub mod module;
pub mod offset_of;
+pub mod qdev;
+pub mod qom;
pub mod sysbus;
pub mod vmstate;
pub mod zeroable;
--- /dev/null
+// Copyright 2024, Linaro Limited
+// Author(s): Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+//! Macro to register blocks of code that run as QEMU starts up.
+
+#[macro_export]
+macro_rules! module_init {
+ ($type:ident => $body:block) => {
+ const _: () = {
+ #[used]
+ #[cfg_attr(
+ not(any(target_vendor = "apple", target_os = "windows")),
+ link_section = ".init_array"
+ )]
+ #[cfg_attr(target_vendor = "apple", link_section = "__DATA,__mod_init_func")]
+ #[cfg_attr(target_os = "windows", link_section = ".CRT$XCU")]
+ pub static LOAD_MODULE: extern "C" fn() = {
+ extern "C" fn init_fn() {
+ $body
+ }
+
+ extern "C" fn ctor_fn() {
+ unsafe {
+ $crate::bindings::register_module_init(
+ Some(init_fn),
+ $crate::bindings::module_init_type::$type,
+ );
+ }
+ }
+
+ ctor_fn
+ };
+ };
+ };
+
+ // shortcut because it's quite common that $body needs unsafe {}
+ ($type:ident => unsafe $body:block) => {
+ $crate::module_init! {
+ $type => { unsafe { $body } }
+ }
+ };
+}
pub use crate::cell::BqlCell;
pub use crate::cell::BqlRefCell;
-pub use crate::definitions::ObjectType;
+pub use crate::qom::ObjectType;
--- /dev/null
+// Copyright 2024, Linaro Limited
+// Author(s): Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+//! Bindings to create devices and access device functionality from Rust.
+
+use std::ffi::CStr;
+
+use crate::{
+ bindings::{self, DeviceClass, DeviceState, Error, ObjectClass, Property, VMStateDescription},
+ prelude::*,
+ qom::ClassInitImpl,
+};
+
+/// Trait providing the contents of [`DeviceClass`].
+pub trait DeviceImpl {
+ /// _Realization_ is the second stage of device creation. It contains
+ /// all operations that depend on device properties and can fail (note:
+ /// this is not yet supported for Rust devices).
+ ///
+ /// If not `None`, the parent class's `realize` method is overridden
+ /// with the function pointed to by `REALIZE`.
+ const REALIZE: Option<fn(&mut Self)> = None;
+
+ /// If not `None`, the parent class's `reset` method is overridden
+ /// with the function pointed to by `RESET`.
+ ///
+ /// Rust does not yet support the three-phase reset protocol; this is
+ /// usually okay for leaf classes.
+ const RESET: Option<fn(&mut Self)> = None;
+
+ /// An array providing the properties that the user can set on the
+ /// device. Not a `const` because referencing statics in constants
+ /// is unstable until Rust 1.83.0.
+ fn properties() -> &'static [Property] {
+ &[]
+ }
+
+ /// A `VMStateDescription` providing the migration format for the device
+ /// Not a `const` because referencing statics in constants is unstable
+ /// until Rust 1.83.0.
+ fn vmsd() -> Option<&'static VMStateDescription> {
+ None
+ }
+}
+
+/// # Safety
+///
+/// This function is only called through the QOM machinery and
+/// used by the `ClassInitImpl<DeviceClass>` trait.
+/// We expect the FFI user of this function to pass a valid pointer that
+/// can be downcasted to type `T`. We also expect the device is
+/// readable/writeable from one thread at any time.
+unsafe extern "C" fn rust_realize_fn<T: DeviceImpl>(dev: *mut DeviceState, _errp: *mut *mut Error) {
+ assert!(!dev.is_null());
+ let state = dev.cast::<T>();
+ T::REALIZE.unwrap()(unsafe { &mut *state });
+}
+
+/// # Safety
+///
+/// We expect the FFI user of this function to pass a valid pointer that
+/// can be downcasted to type `T`. We also expect the device is
+/// readable/writeable from one thread at any time.
+unsafe extern "C" fn rust_reset_fn<T: DeviceImpl>(dev: *mut DeviceState) {
+ assert!(!dev.is_null());
+ let state = dev.cast::<T>();
+ T::RESET.unwrap()(unsafe { &mut *state });
+}
+
+impl<T> ClassInitImpl<DeviceClass> for T
+where
+ T: ClassInitImpl<ObjectClass> + DeviceImpl,
+{
+ fn class_init(dc: &mut DeviceClass) {
+ if <T as DeviceImpl>::REALIZE.is_some() {
+ dc.realize = Some(rust_realize_fn::<T>);
+ }
+ if <T as DeviceImpl>::RESET.is_some() {
+ unsafe {
+ bindings::device_class_set_legacy_reset(dc, Some(rust_reset_fn::<T>));
+ }
+ }
+ if let Some(vmsd) = <T as DeviceImpl>::vmsd() {
+ dc.vmsd = vmsd;
+ }
+ let prop = <T as DeviceImpl>::properties();
+ if !prop.is_empty() {
+ unsafe {
+ bindings::device_class_set_props_n(dc, prop.as_ptr(), prop.len());
+ }
+ }
+
+ <T as ClassInitImpl<ObjectClass>>::class_init(&mut dc.parent_class);
+ }
+}
+
+#[macro_export]
+macro_rules! define_property {
+ ($name:expr, $state:ty, $field:ident, $prop:expr, $type:ty, default = $defval:expr$(,)*) => {
+ $crate::bindings::Property {
+ // use associated function syntax for type checking
+ name: ::std::ffi::CStr::as_ptr($name),
+ info: $prop,
+ offset: $crate::offset_of!($state, $field) as isize,
+ set_default: true,
+ defval: $crate::bindings::Property__bindgen_ty_1 { u: $defval as u64 },
+ ..$crate::zeroable::Zeroable::ZERO
+ }
+ };
+ ($name:expr, $state:ty, $field:ident, $prop:expr, $type:ty$(,)*) => {
+ $crate::bindings::Property {
+ // use associated function syntax for type checking
+ name: ::std::ffi::CStr::as_ptr($name),
+ info: $prop,
+ offset: $crate::offset_of!($state, $field) as isize,
+ set_default: false,
+ ..$crate::zeroable::Zeroable::ZERO
+ }
+ };
+}
+
+#[macro_export]
+macro_rules! declare_properties {
+ ($ident:ident, $($prop:expr),*$(,)*) => {
+ pub static $ident: [$crate::bindings::Property; {
+ let mut len = 0;
+ $({
+ _ = stringify!($prop);
+ len += 1;
+ })*
+ len
+ }] = [
+ $($prop),*,
+ ];
+ };
+}
+
+unsafe impl ObjectType for DeviceState {
+ type Class = DeviceClass;
+ const TYPE_NAME: &'static CStr =
+ unsafe { CStr::from_bytes_with_nul_unchecked(bindings::TYPE_DEVICE) };
+}
--- /dev/null
+// Copyright 2024, Linaro Limited
+// Author(s): Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+//! Bindings to access QOM functionality from Rust.
+//!
+//! This module provides automatic creation and registration of `TypeInfo`
+//! for classes that are written in Rust, and mapping between Rust traits
+//! and QOM vtables.
+//!
+//! # Structure of a class
+//!
+//! A leaf class only needs a struct holding instance state. The struct must
+//! implement the [`ObjectType`] trait, as well as any `*Impl` traits that exist
+//! for its superclasses.
+//!
+//! If a class has subclasses, it will also provide a struct for instance data,
+//! with the same characteristics as for concrete classes, but it also needs
+//! additional components to support virtual methods:
+//!
+//! * a struct for class data, for example `DeviceClass`. This corresponds to
+//! the C "class struct" and holds the vtable that is used by instances of the
+//! class and its subclasses. It must start with its parent's class struct.
+//!
+//! * a trait for virtual method implementations, for example `DeviceImpl`.
+//! Child classes implement this trait to provide their own behavior for
+//! virtual methods. The trait's methods take `&self` to access instance data.
+//!
+//! * an implementation of [`ClassInitImpl`], for example
+//! `ClassInitImpl<DeviceClass>`. This fills the vtable in the class struct;
+//! the source for this is the `*Impl` trait; the associated consts and
+//! functions if needed are wrapped to map C types into Rust types.
+
+use std::{ffi::CStr, os::raw::c_void};
+
+use crate::bindings::{self, Object, ObjectClass, TypeInfo};
+
+unsafe extern "C" fn rust_instance_init<T: ObjectImpl>(obj: *mut Object) {
+ // SAFETY: obj is an instance of T, since rust_instance_init<T>
+ // is called from QOM core as the instance_init function
+ // for class T
+ unsafe { T::INSTANCE_INIT.unwrap()(&mut *obj.cast::<T>()) }
+}
+
+unsafe extern "C" fn rust_instance_post_init<T: ObjectImpl>(obj: *mut Object) {
+ // SAFETY: obj is an instance of T, since rust_instance_post_init<T>
+ // is called from QOM core as the instance_post_init function
+ // for class T
+ //
+ // FIXME: it's not really guaranteed that there are no backpointers to
+ // obj; it's quite possible that they have been created by instance_init().
+ // The receiver should be &self, not &mut self.
+ T::INSTANCE_POST_INIT.unwrap()(unsafe { &mut *obj.cast::<T>() })
+}
+
+unsafe extern "C" fn rust_class_init<T: ObjectType + ClassInitImpl<T::Class>>(
+ klass: *mut ObjectClass,
+ _data: *mut c_void,
+) {
+ // SAFETY: klass is a T::Class, since rust_class_init<T>
+ // is called from QOM core as the class_init function
+ // for class T
+ T::class_init(unsafe { &mut *klass.cast::<T::Class>() })
+}
+
+/// Trait exposed by all structs corresponding to QOM objects.
+///
+/// # Safety
+///
+/// For classes declared in C:
+///
+/// - `Class` and `TYPE` must match the data in the `TypeInfo`;
+///
+/// - the first field of the struct must be of the instance type corresponding
+/// to the superclass, as declared in the `TypeInfo`
+///
+/// - likewise, the first field of the `Class` struct must be of the class type
+/// corresponding to the superclass
+///
+/// For classes declared in Rust and implementing [`ObjectImpl`]:
+///
+/// - the struct must be `#[repr(C)]`;
+///
+/// - the first field of the struct must be of the instance struct corresponding
+/// to the superclass, which is `ObjectImpl::ParentType`
+///
+/// - likewise, the first field of the `Class` must be of the class struct
+/// corresponding to the superclass, which is `ObjectImpl::ParentType::Class`.
+pub unsafe trait ObjectType: Sized {
+ /// The QOM class object corresponding to this struct. This is used
+ /// to automatically generate a `class_init` method.
+ type Class;
+
+ /// The name of the type, which can be passed to `object_new()` to
+ /// generate an instance of this type.
+ const TYPE_NAME: &'static CStr;
+}
+
+/// Trait a type must implement to be registered with QEMU.
+pub trait ObjectImpl: ObjectType + ClassInitImpl<Self::Class> {
+ /// The parent of the type. This should match the first field of
+ /// the struct that implements `ObjectImpl`:
+ type ParentType: ObjectType;
+
+ /// Whether the object can be instantiated
+ const ABSTRACT: bool = false;
+ const INSTANCE_FINALIZE: Option<unsafe extern "C" fn(obj: *mut Object)> = None;
+
+ /// Function that is called to initialize an object. The parent class will
+ /// have already been initialized so the type is only responsible for
+ /// initializing its own members.
+ ///
+ /// FIXME: The argument is not really a valid reference. `&mut
+ /// MaybeUninit<Self>` would be a better description.
+ const INSTANCE_INIT: Option<unsafe fn(&mut Self)> = None;
+
+ /// Function that is called to finish initialization of an object, once
+ /// `INSTANCE_INIT` functions have been called.
+ const INSTANCE_POST_INIT: Option<fn(&mut Self)> = None;
+
+ /// Called on descendent classes after all parent class initialization
+ /// has occurred, but before the class itself is initialized. This
+ /// is only useful if a class is not a leaf, and can be used to undo
+ /// the effects of copying the contents of the parent's class struct
+ /// to the descendants.
+ const CLASS_BASE_INIT: Option<
+ unsafe extern "C" fn(klass: *mut ObjectClass, data: *mut c_void),
+ > = None;
+
+ const TYPE_INFO: TypeInfo = TypeInfo {
+ name: Self::TYPE_NAME.as_ptr(),
+ parent: Self::ParentType::TYPE_NAME.as_ptr(),
+ instance_size: core::mem::size_of::<Self>(),
+ instance_align: core::mem::align_of::<Self>(),
+ instance_init: match Self::INSTANCE_INIT {
+ None => None,
+ Some(_) => Some(rust_instance_init::<Self>),
+ },
+ instance_post_init: match Self::INSTANCE_POST_INIT {
+ None => None,
+ Some(_) => Some(rust_instance_post_init::<Self>),
+ },
+ instance_finalize: Self::INSTANCE_FINALIZE,
+ abstract_: Self::ABSTRACT,
+ class_size: core::mem::size_of::<Self::Class>(),
+ class_init: Some(rust_class_init::<Self>),
+ class_base_init: Self::CLASS_BASE_INIT,
+ class_data: core::ptr::null_mut(),
+ interfaces: core::ptr::null_mut(),
+ };
+
+ // methods on ObjectClass
+ const UNPARENT: Option<fn(&Self)> = None;
+}
+
+/// Internal trait used to automatically fill in a class struct.
+///
+/// Each QOM class that has virtual methods describes them in a
+/// _class struct_. Class structs include a parent field corresponding
+/// to the vtable of the parent class, all the way up to [`ObjectClass`].
+/// Each QOM type has one such class struct; this trait takes care of
+/// initializing the `T` part of the class struct, for the type that
+/// implements the trait.
+///
+/// Each struct will implement this trait with `T` equal to each
+/// superclass. For example, a device should implement at least
+/// `ClassInitImpl<`[`DeviceClass`](crate::bindings::DeviceClass)`>` and
+/// `ClassInitImpl<`[`ObjectClass`](crate::bindings::ObjectClass)`>`.
+/// Such implementations are made in one of two ways.
+///
+/// For most superclasses, `ClassInitImpl` is provided by the `qemu-api`
+/// crate itself. The Rust implementation of methods will come from a
+/// trait like [`ObjectImpl`] or [`DeviceImpl`](crate::qdev::DeviceImpl),
+/// and `ClassInitImpl` is provided by blanket implementations that
+/// operate on all implementors of the `*Impl`* trait. For example:
+///
+/// ```ignore
+/// impl<T> ClassInitImpl<DeviceClass> for T
+/// where
+/// T: ClassInitImpl<ObjectClass> + DeviceImpl,
+/// ```
+///
+/// The bound on `ClassInitImpl<ObjectClass>` is needed so that,
+/// after initializing the `DeviceClass` part of the class struct,
+/// the parent [`ObjectClass`] is initialized as well.
+///
+/// The other case is when manual implementation of the trait is needed.
+/// This covers the following cases:
+///
+/// * if a class implements a QOM interface, the Rust code _has_ to define its
+/// own class struct `FooClass` and implement `ClassInitImpl<FooClass>`.
+/// `ClassInitImpl<FooClass>`'s `class_init` method will then forward to
+/// multiple other `class_init`s, for the interfaces as well as the
+/// superclass. (Note that there is no Rust example yet for using interfaces).
+///
+/// * for classes implemented outside the ``qemu-api`` crate, it's not possible
+/// to add blanket implementations like the above one, due to orphan rules. In
+/// that case, the easiest solution is to implement
+/// `ClassInitImpl<YourSuperclass>` for each subclass and not have a
+/// `YourSuperclassImpl` trait at all.
+///
+/// ```ignore
+/// impl ClassInitImpl<YourSuperclass> for YourSubclass {
+/// fn class_init(klass: &mut YourSuperclass) {
+/// klass.some_method = Some(Self::some_method);
+/// <Self as ClassInitImpl<SysBusDeviceClass>>::class_init(&mut klass.parent_class);
+/// }
+/// }
+/// ```
+///
+/// While this method incurs a small amount of code duplication,
+/// it is generally limited to the recursive call on the last line.
+/// This is because classes defined in Rust do not need the same
+/// glue code that is needed when the classes are defined in C code.
+/// You may consider using a macro if you have many subclasses.
+pub trait ClassInitImpl<T> {
+ /// Initialize `klass` to point to the virtual method implementations
+ /// for `Self`. On entry, the virtual method pointers are set to
+ /// the default values coming from the parent classes; the function
+ /// can change them to override virtual methods of a parent class.
+ ///
+ /// The virtual method implementations usually come from another
+ /// trait, for example [`DeviceImpl`](crate::qdev::DeviceImpl)
+ /// when `T` is [`DeviceClass`](crate::bindings::DeviceClass).
+ ///
+ /// On entry, `klass`'s parent class is initialized, while the other fields
+ /// are all zero; it is therefore assumed that all fields in `T` can be
+ /// zeroed, otherwise it would not be possible to provide the class as a
+ /// `&mut T`. TODO: add a bound of [`Zeroable`](crate::zeroable::Zeroable)
+ /// to T; this is more easily done once Zeroable does not require a manual
+ /// implementation (Rust 1.75.0).
+ fn class_init(klass: &mut T);
+}
+
+/// # Safety
+///
+/// We expect the FFI user of this function to pass a valid pointer that
+/// can be downcasted to type `T`. We also expect the device is
+/// readable/writeable from one thread at any time.
+unsafe extern "C" fn rust_unparent_fn<T: ObjectImpl>(dev: *mut Object) {
+ unsafe {
+ assert!(!dev.is_null());
+ let state = core::ptr::NonNull::new_unchecked(dev.cast::<T>());
+ T::UNPARENT.unwrap()(state.as_ref());
+ }
+}
+
+impl<T> ClassInitImpl<ObjectClass> for T
+where
+ T: ObjectImpl,
+{
+ fn class_init(oc: &mut ObjectClass) {
+ if <T as ObjectImpl>::UNPARENT.is_some() {
+ oc.unparent = Some(rust_unparent_fn::<T>);
+ }
+ }
+}
+
+unsafe impl ObjectType for Object {
+ type Class = ObjectClass;
+ const TYPE_NAME: &'static CStr =
+ unsafe { CStr::from_bytes_with_nul_unchecked(bindings::TYPE_OBJECT) };
+}
use crate::{
bindings::{self, DeviceClass},
cell::bql_locked,
- definitions::ClassInitImpl,
irq::InterruptSource,
prelude::*,
+ qom::ClassInitImpl,
};
unsafe impl ObjectType for SysBusDevice {
use std::ffi::CStr;
use qemu_api::{
- bindings::*, c_str, declare_properties, define_property, definitions::ObjectImpl,
- device_class::DeviceImpl, impl_device_class, prelude::*, zeroable::Zeroable,
+ bindings::*, c_str, declare_properties, define_property, prelude::*, qdev::DeviceImpl,
+ qom::ObjectImpl, zeroable::Zeroable,
};
#[test]
projects / qemu.git / commitdiff