From: Paolo Bonzini <pbonzini@redhat.com>
Date: Fri, 14 Feb 2025 13:10:38 +0000 (+0100)
Subject: rust: cell: add full example of declaring a SysBusDevice
X-Git-Tag: v10.0.0-rc0~19^2~3
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=5778ce99971f7e09952a1efbac91d0c97d7a0fee;p=thirdparty%2Fqemu.git

rust: cell: add full example of declaring a SysBusDevice

Reviewed-by: Zhao Liu <zhao1.liu@intel.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---

diff --git a/rust/qemu-api/src/cell.rs b/rust/qemu-api/src/cell.rs
index 448638e896..ab0785a269 100644
--- a/rust/qemu-api/src/cell.rs
+++ b/rust/qemu-api/src/cell.rs
@@ -73,6 +73,34 @@
 //! 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 PL061State {
+//! #     type Class = <SysBusDevice as ObjectType>::Class;
+//! #     const TYPE_NAME: &'static std::ffi::CStr = c_str!("pl061");
+//! # }
+//! struct PL061State {
+//!     parent_obj: ParentField<SysBusDevice>,
+//!
+//!     // Configuration is read-only after initialization
+//!     pullups: u32,
+//!     pulldowns: u32,
+//!
+//!     // Single values shared with C code use BqlCell, in this case via InterruptSource
+//!     out: [InterruptSource; N_GPIOS],
+//!     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