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
where
    <Self as Deref>::Target: ObjectType,
{
    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;
}

impl<T: ObjectType> ObjectCast for &T {}

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. The idea is that you can operate as if deref coercion could also convert to superclasses.

It is implemented as follows

pub trait ObjectMethods: Deref
where
    Self::Target: IsA<Object>,
{
    /// Remove the object from the QOM tree
    fn unparent(&self) {
        let obj = self.upcast::<Object>();
        // SAFETY: safety of this is the requirement for implementing IsA
        unsafe {
            object_unparent(obj.as_ptr_mut());
        }
    }
}

impl<R: Deref> ObjectMethods for R where R::Target: IsA<Object> {}

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) -> qom::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).
  • 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.
• instance_finalize implemented automatically via drop_in_place

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