Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 rust/qemu-api/src/cell.rs | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/rust/qemu-api/src/cell.rs b/rust/qemu-api/src/cell.rs
index 6db678161ff..13e267ad355 100644
--- a/rust/qemu-api/src/cell.rs
+++ b/rust/qemu-api/src/cell.rs
@@ -73,6 +73,36 @@
 //! QEMU device implementations is usually incorrect and can lead to
 //! thread-safety issues.
 //!
+//! ### Example
+//!
+//! ```
+//! # use qemu_api::prelude::*;
+//! # use qemu_api::{c_str, cell::BqlRefCell, irq::InterruptSource, irq::IRQState};
+//! # use qemu_api::{sysbus::SysBusDevice, qom::Owned, qom::ParentField};
+//! # const N_GPIOS: usize = 8;
+//! # struct PL061Registers { /* ... */ }
+//! # unsafe impl ObjectType for PL061Device {
+//! #     type Class = <SysBusDevice as ObjectType>::Class;
+//! #     const TYPE_NAME: &'static std::ffi::CStr = c_str!("pl061");
+//! # }
+//! struct PL061Device {
+//!     parent_obj: ParentField<SysBusDevice>,
+//!
+//!     // Configuration is read-only after initialization
+//!     pullups: u32,
+//!     pulldowns: u32,
+//!
+//!     // Same for sub-objects of the device
+//!     out: [Owned<IRQState>; N_GPIOS],
+//!
+//!     // Single values shared with C code use BqlCell, in this case via InterruptSource
+//!     interrupt: InterruptSource,
+//!
+//!     // Larger state accessed by device methods uses BqlRefCell or Mutex
+//!     registers: BqlRefCell<PL061Registers>,
+//! }
+//! ```
+//!
 //! ### `BqlCell<T>`
 //!
 //! [`BqlCell<T>`] implements interior mutability by moving values in and out of
-- 
2.48.1

> +//! ### Example
> +//!
> +//! ```
> +//! # use qemu_api::prelude::*;
> +//! # use qemu_api::{c_str, cell::BqlRefCell, irq::InterruptSource, irq::IRQState};
> +//! # use qemu_api::{sysbus::SysBusDevice, qom::Owned, qom::ParentField};
> +//! # const N_GPIOS: usize = 8;
> +//! # struct PL061Registers { /* ... */ }
> +//! # unsafe impl ObjectType for PL061Device {
> +//! #     type Class = <SysBusDevice as ObjectType>::Class;
> +//! #     const TYPE_NAME: &'static std::ffi::CStr = c_str!("pl061");
> +//! # }
> +//! struct PL061Device {

Maybe PL061State?

> +//!     parent_obj: ParentField<SysBusDevice>,
> +//!
> +//!     // Configuration is read-only after initialization
> +//!     pullups: u32,
> +//!     pulldowns: u32,
> +//!
> +//!     // Same for sub-objects of the device
> +//!     out: [Owned<IRQState>; N_GPIOS],

Should this be InterruptSource type?

Just have a quick look at pl061.c:

qdev_init_gpio_out(dev, s->out, N_GPIOS);

So in Rust side, `out` would be initialized by
DeviceMethods::init_gpio_out().


Others are fine for me ~ with above nits fixed,

Reviewed-by: Zhao Liu <zhao1.liu@intel.com>

On 3/4/25 18:04, Zhao Liu wrote:
>> +//! struct PL061Device {
> 
> Maybe PL061State?
> 
>> +//!     parent_obj: ParentField<SysBusDevice>,
>> +//!
>> +//!     // Configuration is read-only after initialization
>> +//!     pullups: u32,
>> +//!     pulldowns: u32,
>> +//!
>> +//!     // Same for sub-objects of the device
>> +//!     out: [Owned<IRQState>; N_GPIOS],
> 
> Should this be InterruptSource type?
> 
> Just have a quick look at pl061.c:
> 
> qdev_init_gpio_out(dev, s->out, N_GPIOS);
> 
> So in Rust side, `out` would be initialized by
> DeviceMethods::init_gpio_out().
> 
> 
> Others are fine for me ~ with above nits fixed,
> 
> Reviewed-by: Zhao Liu <zhao1.liu@intel.com>
Yes, all good points.  Looks like we're set for 10.0 soft freeze. :)

Paolo