Features/Rust/QOM

Rust QOM interoperability design, very loosely inspired by glib-rs.

Passing objects around

ObjectCast

• trait for performing casts on objects
• upcasts safe at compile time, downcasts safe at runtime
• implemented by &T
• casting &T produces &U

pub trait ObjectCast: Copy + Deref {
    fn as_ref(&self) -> &Self::Target;
    fn upcast<U: ObjectType>(self) -> &U where Self::Target: IsA<U>;
    fn downcast<U: IsA<Self::Target>>(self) -> Option<&U>;
    fn dynamic_cast<U: ObjectType>(self) -> Option<&U>;
    unsafe fn unsafe_cast<U: ObjectType>(self) -> &U;
}

qom::Arc<T>

• T is a struct for a QOM object
• cloning qom::Arc calls object_ref, dropping qom::Arc calls object_unref
• possible to go (unsafely) from &T to Arc<T>
• associated functions for casting owned references similar to the above (except downcast/dynamic_cast returns Result<Arc<U>, Arc<T>>)
• consider renaming this to Owned<> or (similar to Linux) ARef<>?

Calling methods (bindings to classes implemented in C)

All methods receive &self (interior mutability). Rust implementation needs to wrap state with Cell<>, RefCell<> or Mutex<>

Two traits describe the hierarchy and provide the mapping from Rust types to C string names:

pub unsafe trait IsA<P: ObjectType>: ObjectType {}

pub unsafe trait ObjectType: Sized {
    const TYPE: &'static CStr;
    fn new() -> qom::Arc<Self> { ... }
}

Each class is composed of:

• one struct that provides the layout. It implements ObjectType and IsA<> for each direct or indirect parent
• methods are placed on a trait for non-final classes. The trait is automatically visible to all structs that implement IsA for that class.

Each interface only has the latter.

Struct

Object, Device, ...

• defines constructors
• defines methods of final classes

trait

ObjectMethods, DeviceMethods, UserCreatableMethods, ...

• defines methods of non-final classes and interfaces, for example ObjectMethods::typename(&self)
• automatically implemented by &T or qom::Arc<T> where T is a subclass

pub unsafe trait ObjectMethods: Deref
where
    <Self as Deref>::Target: IsA<Object>
{
    ...
}

unsafe impl<T: IsA<Object>, R: Deref<Target = T>> ObjectMethods for R {}

Defining QOM classes in Rust

struct must be #[repr(C)]

One trait per class if it has virtual functions

pub trait DeviceImpl: ObjectImpl + DeviceTypeImpl {
    const REALIZE: Option<fn(obj: &Self) -> crate::Result<()>> = None;
    const UNREALIZE: Option<fn(obj: &Self)> = None;
    const COLD_RESET: Option<fn(obj: &Self)> = None;
}

Instance-side functions (e.g. fn unrealize(&self)) implemented as private methods and exposed via the above trait; None means use superclass.

Each superclass must implement a function like

    pub unsafe extern "C" fn rust_class_init<T: DeviceImpl>(klass: *mut c_void) ...

The function becomes the subclass's class_init and that daisy-chains to the superclass's rust_class_init. It sets up QOM to call these functions via unsafe wrappers:

unsafe extern "C" fn rust_cold_reset<T: DeviceImpl>(obj: *mut DeviceState) {
    let f = T::COLD_RESET.unwrap();
    f((&*obj).unsafe_cast::<T>())
}
if T::COLD_RESET.is_some() {
    self.cold_reset = rust_cold_reset::<T>; // self is &mut DeviceClass
}

Rust implementation types contain a configuration part (implements Default + ConstDefault) and a state part (implements Default):

• instance_init is implemented automatically via Default/ConstDefault trait (using MaybeUninit to move the default values into the struct).
• instance_finalize implemented automatically via drop_in_place

Possible change in common code: pre_init hook that replaces memset(obj, 0, type->instance_size)? This would allow filling in the default values of the configuration fields before property initialization. This is safer, because otherwise we have to rely entirely on qdev properties to initialize the configuration fields.

TODO

• Creating new objects requires object_property_set* wrappers

• Defining classes not part of qdev (i.e. not under DeviceState) is not considered because properties would require full-blown Visitor support. Alternative: Features/QOM-QAPI_integration