|
@@ -40,11 +40,6 @@
|
|
//! The traits have the appropriate specialization of `IsA<>` as a supertrait,
|
|
//! The traits have the appropriate specialization of `IsA<>` as a supertrait,
|
|
//! for example `IsA<DeviceState>` for `DeviceImpl`.
|
|
//! for example `IsA<DeviceState>` for `DeviceImpl`.
|
|
//!
|
|
//!
|
|
-//! * 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.
|
|
|
|
-//!
|
|
|
|
//! * a trait for instance methods, for example `DeviceMethods`. This trait is
|
|
//! * a trait for instance methods, for example `DeviceMethods`. This trait is
|
|
//! automatically implemented for any reference or smart pointer to a device
|
|
//! automatically implemented for any reference or smart pointer to a device
|
|
//! instance. It calls into the vtable provides access across all subclasses
|
|
//! instance. It calls into the vtable provides access across all subclasses
|
|
@@ -54,6 +49,48 @@
|
|
//! This provides access to class-wide functionality that doesn't depend on
|
|
//! This provides access to class-wide functionality that doesn't depend on
|
|
//! instance data. Like instance methods, these are automatically inherited by
|
|
//! instance data. Like instance methods, these are automatically inherited by
|
|
//! child classes.
|
|
//! child classes.
|
|
|
|
+//!
|
|
|
|
+//! # Class structures
|
|
|
|
+//!
|
|
|
|
+//! 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`].
|
|
|
|
+//!
|
|
|
|
+//! As mentioned above, virtual methods are defined via traits such as
|
|
|
|
+//! `DeviceImpl`. Class structs do not define any trait but, conventionally,
|
|
|
|
+//! all of them have a `class_init` method to initialize the virtual methods
|
|
|
|
+//! based on the trait and then call the same method on the superclass.
|
|
|
|
+//!
|
|
|
|
+//! ```ignore
|
|
|
|
+//! impl YourSubclassClass
|
|
|
|
+//! {
|
|
|
|
+//! pub fn class_init<T: YourSubclassImpl>(&mut self) {
|
|
|
|
+//! ...
|
|
|
|
+//! klass.parent_class::class_init<T>();
|
|
|
|
+//! }
|
|
|
|
+//! }
|
|
|
|
+//! ```
|
|
|
|
+//!
|
|
|
|
+//! If a class implements a QOM interface. In that case, the function must
|
|
|
|
+//! contain, for each interface, an extra forwarding call as follows:
|
|
|
|
+//!
|
|
|
|
+//! ```ignore
|
|
|
|
+//! ResettableClass::cast::<Self>(self).class_init::<Self>();
|
|
|
|
+//! ```
|
|
|
|
+//!
|
|
|
|
+//! These `class_init` functions are methods on the class rather than a trait,
|
|
|
|
+//! because the bound on `T` (`DeviceImpl` in this case), will change for every
|
|
|
|
+//! class struct. The functions are pointed to by the
|
|
|
|
+//! [`ObjectImpl::CLASS_INIT`] function pointer. While there is no default
|
|
|
|
+//! implementation, in most cases it will be enough to write it as follows:
|
|
|
|
+//!
|
|
|
|
+//! ```ignore
|
|
|
|
+//! const CLASS_INIT: fn(&mut Self::Class)> = Self::Class::class_init::<Self>;
|
|
|
|
+//! ```
|
|
|
|
+//!
|
|
|
|
+//! This design incurs a small amount of code duplication but, by not using
|
|
|
|
+//! traits, it allows the flexibility of implementing bindings in any crate,
|
|
|
|
+//! without incurring into violations of orphan rules for traits.
|
|
|
|
|
|
use std::{
|
|
use std::{
|
|
ffi::CStr,
|
|
ffi::CStr,
|
|
@@ -279,19 +316,25 @@ pub unsafe trait InterfaceType: Sized {
|
|
/// for this interface.
|
|
/// for this interface.
|
|
const TYPE_NAME: &'static CStr;
|
|
const TYPE_NAME: &'static CStr;
|
|
|
|
|
|
- /// Initialize the vtable for the interface; the generic argument `T` is the
|
|
|
|
- /// type being initialized, while the generic argument `U` is the type that
|
|
|
|
|
|
+ /// Return the vtable for the interface; `U` is the type that
|
|
/// lists the interface in its `TypeInfo`.
|
|
/// lists the interface in its `TypeInfo`.
|
|
///
|
|
///
|
|
|
|
+ /// # Examples
|
|
|
|
+ ///
|
|
|
|
+ /// This function is usually called by a `class_init` method in `U::Class`.
|
|
|
|
+ /// For example, `DeviceClass::class_init<T>` initializes its `Resettable`
|
|
|
|
+ /// interface as follows:
|
|
|
|
+ ///
|
|
|
|
+ /// ```ignore
|
|
|
|
+ /// ResettableClass::cast::<DeviceState>(self).class_init::<T>();
|
|
|
|
+ /// ```
|
|
|
|
+ ///
|
|
|
|
+ /// where `T` is the concrete subclass that is being initialized.
|
|
|
|
+ ///
|
|
/// # Panics
|
|
/// # Panics
|
|
///
|
|
///
|
|
/// Panic if the incoming argument if `T` does not implement the interface.
|
|
/// Panic if the incoming argument if `T` does not implement the interface.
|
|
- fn interface_init<
|
|
|
|
- T: ObjectType + ClassInitImpl<Self> + ClassInitImpl<U::Class>,
|
|
|
|
- U: ObjectType,
|
|
|
|
- >(
|
|
|
|
- klass: &mut U::Class,
|
|
|
|
- ) {
|
|
|
|
|
|
+ fn cast<U: ObjectType>(klass: &mut U::Class) -> &mut Self {
|
|
unsafe {
|
|
unsafe {
|
|
// SAFETY: upcasting to ObjectClass is always valid, and the
|
|
// SAFETY: upcasting to ObjectClass is always valid, and the
|
|
// return type is either NULL or the argument itself
|
|
// return type is either NULL or the argument itself
|
|
@@ -300,8 +343,7 @@ fn interface_init<
|
|
Self::TYPE_NAME.as_ptr(),
|
|
Self::TYPE_NAME.as_ptr(),
|
|
)
|
|
)
|
|
.cast();
|
|
.cast();
|
|
-
|
|
|
|
- <T as ClassInitImpl<Self>>::class_init(result.as_mut().unwrap())
|
|
|
|
|
|
+ result.as_mut().unwrap()
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
@@ -558,87 +600,20 @@ pub trait ObjectImpl: ObjectType + IsA<Object> {
|
|
/// the default values coming from the parent classes; the function
|
|
/// the default values coming from the parent classes; the function
|
|
/// can change them to override virtual methods of a parent class.
|
|
/// can change them to override virtual methods of a parent class.
|
|
///
|
|
///
|
|
- /// Usually defined as `<Self as ClassInitImpl<Self::Class>::class_init`.
|
|
|
|
- const CLASS_INIT: fn(&mut Self::Class);
|
|
|
|
-}
|
|
|
|
-
|
|
|
|
-/// 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::qdev::DeviceClass)`>` and
|
|
|
|
-/// `ClassInitImpl<`[`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.
|
|
|
|
|
|
+ /// Usually defined simply as `Self::Class::class_init::<Self>`;
|
|
|
|
+ /// however a default implementation cannot be included here, because the
|
|
|
|
+ /// bounds that the `Self::Class::class_init` method places on `Self` are
|
|
|
|
+ /// not known in advance.
|
|
///
|
|
///
|
|
- /// The virtual method implementations usually come from another
|
|
|
|
- /// trait, for example [`DeviceImpl`](crate::qdev::DeviceImpl)
|
|
|
|
- /// when `T` is [`DeviceClass`](crate::qdev::DeviceClass).
|
|
|
|
|
|
+ /// # Safety
|
|
///
|
|
///
|
|
- /// On entry, `klass`'s parent class is initialized, while the other fields
|
|
|
|
|
|
+ /// While `klass`'s parent class is initialized on entry, the other fields
|
|
/// are all zero; it is therefore assumed that all fields in `T` can be
|
|
/// 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
|
|
/// zeroed, otherwise it would not be possible to provide the class as a
|
|
/// `&mut T`. TODO: add a bound of [`Zeroable`](crate::zeroable::Zeroable)
|
|
/// `&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
|
|
/// to T; this is more easily done once Zeroable does not require a manual
|
|
/// implementation (Rust 1.75.0).
|
|
/// implementation (Rust 1.75.0).
|
|
- fn class_init(klass: &mut T);
|
|
|
|
|
|
+ const CLASS_INIT: fn(&mut Self::Class);
|
|
}
|
|
}
|
|
|
|
|
|
/// # Safety
|
|
/// # Safety
|
|
@@ -651,13 +626,12 @@ pub trait ClassInitImpl<T> {
|
|
T::UNPARENT.unwrap()(unsafe { state.as_ref() });
|
|
T::UNPARENT.unwrap()(unsafe { state.as_ref() });
|
|
}
|
|
}
|
|
|
|
|
|
-impl<T> ClassInitImpl<ObjectClass> for T
|
|
|
|
-where
|
|
|
|
- T: ObjectImpl,
|
|
|
|
-{
|
|
|
|
- fn class_init(oc: &mut ObjectClass) {
|
|
|
|
|
|
+impl ObjectClass {
|
|
|
|
+ /// Fill in the virtual methods of `ObjectClass` based on the definitions in
|
|
|
|
+ /// the `ObjectImpl` trait.
|
|
|
|
+ pub fn class_init<T: ObjectImpl>(&mut self) {
|
|
if <T as ObjectImpl>::UNPARENT.is_some() {
|
|
if <T as ObjectImpl>::UNPARENT.is_some() {
|
|
- oc.unparent = Some(rust_unparent_fn::<T>);
|
|
|
|
|
|
+ self.unparent = Some(rust_unparent_fn::<T>);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|