A full match would mean calling them qom::object and hw::core::qdev. For now,
keep the names shorter but still a bit easier to find.
Reviewed-by: Zhao Liu <zhao1.liu@intel.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
rust/hw/char/pl011/src/device.rs | 4 +-
rust/qemu-api-macros/src/lib.rs | 2 +-
rust/qemu-api/meson.build | 5 +-
rust/qemu-api/src/lib.rs | 5 +-
rust/qemu-api/src/module.rs | 43 +++++++++++
rust/qemu-api/src/prelude.rs | 2 +-
.../qemu-api/src/{device_class.rs => qdev.rs} | 4 +-
rust/qemu-api/src/{definitions.rs => qom.rs} | 76 ++++++++-----------
rust/qemu-api/src/sysbus.rs | 2 +-
rust/qemu-api/tests/tests.rs | 4 +-
10 files changed, 91 insertions(+), 56 deletions(-)
create mode 100644 rust/qemu-api/src/module.rs
rename rust/qemu-api/src/{device_class.rs => qdev.rs} (97%)
rename rust/qemu-api/src/{definitions.rs => qom.rs} (84%)
diff --git a/rust/hw/char/pl011/src/device.rs b/rust/hw/char/pl011/src/device.rs
index d9e9f35f456..3fed8b4ad25 100644
--- a/rust/hw/char/pl011/src/device.rs
+++ b/rust/hw/char/pl011/src/device.rs
@@ -11,10 +11,10 @@
use qemu_api::{
bindings::{self, *},
c_str,
- definitions::ObjectImpl,
- device_class::DeviceImpl,
irq::InterruptSource,
prelude::*,
+ qdev::DeviceImpl,
+ qom::ObjectImpl,
};
use crate::{
diff --git a/rust/qemu-api-macros/src/lib.rs b/rust/qemu-api-macros/src/lib.rs
index cf99ac04b8f..74a8bc7503e 100644
--- a/rust/qemu-api-macros/src/lib.rs
+++ b/rust/qemu-api-macros/src/lib.rs
@@ -40,7 +40,7 @@ pub fn derive_object(input: TokenStream) -> TokenStream {
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);
}
}
};
diff --git a/rust/qemu-api/meson.build b/rust/qemu-api/meson.build
index adcee661150..7ff408ad68e 100644
--- a/rust/qemu-api/meson.build
+++ b/rust/qemu-api/meson.build
@@ -19,11 +19,12 @@ _qemu_api_rs = static_library(
'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',
diff --git a/rust/qemu-api/src/lib.rs b/rust/qemu-api/src/lib.rs
index 9e007e16354..124bece0449 100644
--- a/rust/qemu-api/src/lib.rs
+++ b/rust/qemu-api/src/lib.rs
@@ -15,10 +15,11 @@
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;
diff --git a/rust/qemu-api/src/module.rs b/rust/qemu-api/src/module.rs
new file mode 100644
index 00000000000..fa5cea3598f
--- /dev/null
+++ b/rust/qemu-api/src/module.rs
@@ -0,0 +1,43 @@
+// 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 } }
+ }
+ };
+}
diff --git a/rust/qemu-api/src/prelude.rs b/rust/qemu-api/src/prelude.rs
index 1b8677b2d9a..5cc41f081f9 100644
--- a/rust/qemu-api/src/prelude.rs
+++ b/rust/qemu-api/src/prelude.rs
@@ -7,4 +7,4 @@
pub use crate::cell::BqlCell;
pub use crate::cell::BqlRefCell;
-pub use crate::definitions::ObjectType;
+pub use crate::qom::ObjectType;
diff --git a/rust/qemu-api/src/device_class.rs b/rust/qemu-api/src/qdev.rs
similarity index 97%
rename from rust/qemu-api/src/device_class.rs
rename to rust/qemu-api/src/qdev.rs
index a9965d1f123..ad4c12d097e 100644
--- a/rust/qemu-api/src/device_class.rs
+++ b/rust/qemu-api/src/qdev.rs
@@ -2,12 +2,14 @@
// 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},
- definitions::ClassInitImpl,
prelude::*,
+ qom::ClassInitImpl,
};
/// Trait providing the contents of [`DeviceClass`].
diff --git a/rust/qemu-api/src/definitions.rs b/rust/qemu-api/src/qom.rs
similarity index 84%
rename from rust/qemu-api/src/definitions.rs
rename to rust/qemu-api/src/qom.rs
index a2481c1fe70..2222d1a5ab9 100644
--- a/rust/qemu-api/src/definitions.rs
+++ b/rust/qemu-api/src/qom.rs
@@ -2,7 +2,34 @@
// Author(s): Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
// SPDX-License-Identifier: GPL-2.0-or-later
-//! Definitions required by QEMU when registering a device.
+//! 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};
@@ -143,10 +170,9 @@ pub trait ObjectImpl: ObjectType + ClassInitImpl<Self::Class> {
///
/// 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:
+/// 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
@@ -194,7 +220,7 @@ pub trait ClassInitImpl<T> {
/// 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)
+ /// 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
@@ -206,44 +232,6 @@ pub trait ClassInitImpl<T> {
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
diff --git a/rust/qemu-api/src/sysbus.rs b/rust/qemu-api/src/sysbus.rs
index 5d15b317405..fa69cadd7c1 100644
--- a/rust/qemu-api/src/sysbus.rs
+++ b/rust/qemu-api/src/sysbus.rs
@@ -9,9 +9,9 @@
use crate::{
bindings::{self, DeviceClass},
cell::bql_locked,
- definitions::ClassInitImpl,
irq::InterruptSource,
prelude::*,
+ qom::ClassInitImpl,
};
unsafe impl ObjectType for SysBusDevice {
diff --git a/rust/qemu-api/tests/tests.rs b/rust/qemu-api/tests/tests.rs
index ed3a555e76d..78f7da474b2 100644
--- a/rust/qemu-api/tests/tests.rs
+++ b/rust/qemu-api/tests/tests.rs
@@ -5,8 +5,8 @@
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]
--
2.47.1