1 // Copyright 2024, Linaro Limited 2 // Author(s): Manos Pitsidianakis <manos.pitsidianakis@linaro.org> 3 // SPDX-License-Identifier: GPL-2.0-or-later 4 5 //! Definitions required by QEMU when registering a device. 6 7 use std::{ffi::CStr, os::raw::c_void}; 8 9 use crate::bindings::{self, Object, ObjectClass, TypeInfo}; 10 11 unsafe extern "C" fn rust_instance_init<T: ObjectImpl>(obj: *mut Object) { 12 // SAFETY: obj is an instance of T, since rust_instance_init<T> 13 // is called from QOM core as the instance_init function 14 // for class T 15 unsafe { T::INSTANCE_INIT.unwrap()(&mut *obj.cast::<T>()) } 16 } 17 18 unsafe extern "C" fn rust_instance_post_init<T: ObjectImpl>(obj: *mut Object) { 19 // SAFETY: obj is an instance of T, since rust_instance_post_init<T> 20 // is called from QOM core as the instance_post_init function 21 // for class T 22 // 23 // FIXME: it's not really guaranteed that there are no backpointers to 24 // obj; it's quite possible that they have been created by instance_init(). 25 // The receiver should be &self, not &mut self. 26 T::INSTANCE_POST_INIT.unwrap()(unsafe { &mut *obj.cast::<T>() }) 27 } 28 29 unsafe extern "C" fn rust_class_init<T: ObjectType + ClassInitImpl<T::Class>>( 30 klass: *mut ObjectClass, 31 _data: *mut c_void, 32 ) { 33 // SAFETY: klass is a T::Class, since rust_class_init<T> 34 // is called from QOM core as the class_init function 35 // for class T 36 T::class_init(unsafe { &mut *klass.cast::<T::Class>() }) 37 } 38 39 /// Trait exposed by all structs corresponding to QOM objects. 40 /// 41 /// # Safety 42 /// 43 /// For classes declared in C: 44 /// 45 /// - `Class` and `TYPE` must match the data in the `TypeInfo`; 46 /// 47 /// - the first field of the struct must be of the instance type corresponding 48 /// to the superclass, as declared in the `TypeInfo` 49 /// 50 /// - likewise, the first field of the `Class` struct must be of the class type 51 /// corresponding to the superclass 52 /// 53 /// For classes declared in Rust and implementing [`ObjectImpl`]: 54 /// 55 /// - the struct must be `#[repr(C)]`; 56 /// 57 /// - the first field of the struct must be of the instance struct corresponding 58 /// to the superclass, which is `ObjectImpl::ParentType` 59 /// 60 /// - likewise, the first field of the `Class` must be of the class struct 61 /// corresponding to the superclass, which is `ObjectImpl::ParentType::Class`. 62 pub unsafe trait ObjectType: Sized { 63 /// The QOM class object corresponding to this struct. This is used 64 /// to automatically generate a `class_init` method. 65 type Class; 66 67 /// The name of the type, which can be passed to `object_new()` to 68 /// generate an instance of this type. 69 const TYPE_NAME: &'static CStr; 70 } 71 72 /// Trait a type must implement to be registered with QEMU. 73 pub trait ObjectImpl: ObjectType + ClassInitImpl<Self::Class> { 74 /// The parent of the type. This should match the first field of 75 /// the struct that implements `ObjectImpl`: 76 type ParentType: ObjectType; 77 78 /// Whether the object can be instantiated 79 const ABSTRACT: bool = false; 80 const INSTANCE_FINALIZE: Option<unsafe extern "C" fn(obj: *mut Object)> = None; 81 82 /// Function that is called to initialize an object. The parent class will 83 /// have already been initialized so the type is only responsible for 84 /// initializing its own members. 85 /// 86 /// FIXME: The argument is not really a valid reference. `&mut 87 /// MaybeUninit<Self>` would be a better description. 88 const INSTANCE_INIT: Option<unsafe fn(&mut Self)> = None; 89 90 /// Function that is called to finish initialization of an object, once 91 /// `INSTANCE_INIT` functions have been called. 92 const INSTANCE_POST_INIT: Option<fn(&mut Self)> = None; 93 94 /// Called on descendent classes after all parent class initialization 95 /// has occurred, but before the class itself is initialized. This 96 /// is only useful if a class is not a leaf, and can be used to undo 97 /// the effects of copying the contents of the parent's class struct 98 /// to the descendants. 99 const CLASS_BASE_INIT: Option< 100 unsafe extern "C" fn(klass: *mut ObjectClass, data: *mut c_void), 101 > = None; 102 103 const TYPE_INFO: TypeInfo = TypeInfo { 104 name: Self::TYPE_NAME.as_ptr(), 105 parent: Self::ParentType::TYPE_NAME.as_ptr(), 106 instance_size: core::mem::size_of::<Self>(), 107 instance_align: core::mem::align_of::<Self>(), 108 instance_init: match Self::INSTANCE_INIT { 109 None => None, 110 Some(_) => Some(rust_instance_init::<Self>), 111 }, 112 instance_post_init: match Self::INSTANCE_POST_INIT { 113 None => None, 114 Some(_) => Some(rust_instance_post_init::<Self>), 115 }, 116 instance_finalize: Self::INSTANCE_FINALIZE, 117 abstract_: Self::ABSTRACT, 118 class_size: core::mem::size_of::<Self::Class>(), 119 class_init: Some(rust_class_init::<Self>), 120 class_base_init: Self::CLASS_BASE_INIT, 121 class_data: core::ptr::null_mut(), 122 interfaces: core::ptr::null_mut(), 123 }; 124 125 // methods on ObjectClass 126 const UNPARENT: Option<fn(&Self)> = None; 127 } 128 129 /// Internal trait used to automatically fill in a class struct. 130 /// 131 /// Each QOM class that has virtual methods describes them in a 132 /// _class struct_. Class structs include a parent field corresponding 133 /// to the vtable of the parent class, all the way up to [`ObjectClass`]. 134 /// Each QOM type has one such class struct; this trait takes care of 135 /// initializing the `T` part of the class struct, for the type that 136 /// implements the trait. 137 /// 138 /// Each struct will implement this trait with `T` equal to each 139 /// superclass. For example, a device should implement at least 140 /// `ClassInitImpl<`[`DeviceClass`](crate::bindings::DeviceClass)`>` and 141 /// `ClassInitImpl<`[`ObjectClass`](crate::bindings::ObjectClass)`>`. 142 /// Such implementations are made in one of two ways. 143 /// 144 /// For most superclasses, `ClassInitImpl` is provided by the `qemu-api` 145 /// crate itself. The Rust implementation of methods will come from a 146 /// trait like [`ObjectImpl`] or 147 /// [`DeviceImpl`](crate::device_class::DeviceImpl), and `ClassInitImpl` is 148 /// provided by blanket implementations that operate on all implementors of the 149 /// `*Impl`* trait. For example: 150 /// 151 /// ```ignore 152 /// impl<T> ClassInitImpl<DeviceClass> for T 153 /// where 154 /// T: ClassInitImpl<ObjectClass> + DeviceImpl, 155 /// ``` 156 /// 157 /// The bound on `ClassInitImpl<ObjectClass>` is needed so that, 158 /// after initializing the `DeviceClass` part of the class struct, 159 /// the parent [`ObjectClass`] is initialized as well. 160 /// 161 /// The other case is when manual implementation of the trait is needed. 162 /// This covers the following cases: 163 /// 164 /// * if a class implements a QOM interface, the Rust code _has_ to define its 165 /// own class struct `FooClass` and implement `ClassInitImpl<FooClass>`. 166 /// `ClassInitImpl<FooClass>`'s `class_init` method will then forward to 167 /// multiple other `class_init`s, for the interfaces as well as the 168 /// superclass. (Note that there is no Rust example yet for using interfaces). 169 /// 170 /// * for classes implemented outside the ``qemu-api`` crate, it's not possible 171 /// to add blanket implementations like the above one, due to orphan rules. In 172 /// that case, the easiest solution is to implement 173 /// `ClassInitImpl<YourSuperclass>` for each subclass and not have a 174 /// `YourSuperclassImpl` trait at all. 175 /// 176 /// ```ignore 177 /// impl ClassInitImpl<YourSuperclass> for YourSubclass { 178 /// fn class_init(klass: &mut YourSuperclass) { 179 /// klass.some_method = Some(Self::some_method); 180 /// <Self as ClassInitImpl<SysBusDeviceClass>>::class_init(&mut klass.parent_class); 181 /// } 182 /// } 183 /// ``` 184 /// 185 /// While this method incurs a small amount of code duplication, 186 /// it is generally limited to the recursive call on the last line. 187 /// This is because classes defined in Rust do not need the same 188 /// glue code that is needed when the classes are defined in C code. 189 /// You may consider using a macro if you have many subclasses. 190 pub trait ClassInitImpl<T> { 191 /// Initialize `klass` to point to the virtual method implementations 192 /// for `Self`. On entry, the virtual method pointers are set to 193 /// the default values coming from the parent classes; the function 194 /// can change them to override virtual methods of a parent class. 195 /// 196 /// The virtual method implementations usually come from another 197 /// trait, for example [`DeviceImpl`](crate::device_class::DeviceImpl) 198 /// when `T` is [`DeviceClass`](crate::bindings::DeviceClass). 199 /// 200 /// On entry, `klass`'s parent class is initialized, while the other fields 201 /// are all zero; it is therefore assumed that all fields in `T` can be 202 /// zeroed, otherwise it would not be possible to provide the class as a 203 /// `&mut T`. TODO: add a bound of [`Zeroable`](crate::zeroable::Zeroable) 204 /// to T; this is more easily done once Zeroable does not require a manual 205 /// implementation (Rust 1.75.0). 206 fn class_init(klass: &mut T); 207 } 208 209 #[macro_export] 210 macro_rules! module_init { 211 ($type:ident => $body:block) => { 212 const _: () = { 213 #[used] 214 #[cfg_attr( 215 not(any(target_vendor = "apple", target_os = "windows")), 216 link_section = ".init_array" 217 )] 218 #[cfg_attr(target_vendor = "apple", link_section = "__DATA,__mod_init_func")] 219 #[cfg_attr(target_os = "windows", link_section = ".CRT$XCU")] 220 pub static LOAD_MODULE: extern "C" fn() = { 221 extern "C" fn init_fn() { 222 $body 223 } 224 225 extern "C" fn ctor_fn() { 226 unsafe { 227 $crate::bindings::register_module_init( 228 Some(init_fn), 229 $crate::bindings::module_init_type::$type, 230 ); 231 } 232 } 233 234 ctor_fn 235 }; 236 }; 237 }; 238 239 // shortcut because it's quite common that $body needs unsafe {} 240 ($type:ident => unsafe $body:block) => { 241 $crate::module_init! { 242 $type => { unsafe { $body } } 243 } 244 }; 245 } 246 247 /// # Safety 248 /// 249 /// We expect the FFI user of this function to pass a valid pointer that 250 /// can be downcasted to type `T`. We also expect the device is 251 /// readable/writeable from one thread at any time. 252 unsafe extern "C" fn rust_unparent_fn<T: ObjectImpl>(dev: *mut Object) { 253 unsafe { 254 assert!(!dev.is_null()); 255 let state = core::ptr::NonNull::new_unchecked(dev.cast::<T>()); 256 T::UNPARENT.unwrap()(state.as_ref()); 257 } 258 } 259 260 impl<T> ClassInitImpl<ObjectClass> for T 261 where 262 T: ObjectImpl, 263 { 264 fn class_init(oc: &mut ObjectClass) { 265 if <T as ObjectImpl>::UNPARENT.is_some() { 266 oc.unparent = Some(rust_unparent_fn::<T>); 267 } 268 } 269 } 270 271 unsafe impl ObjectType for Object { 272 type Class = ObjectClass; 273 const TYPE_NAME: &'static CStr = 274 unsafe { CStr::from_bytes_with_nul_unchecked(bindings::TYPE_OBJECT) }; 275 } 276