1 // SPDX-License-Identifier: MIT 2 // 3 // This file is based on library/core/src/cell.rs from 4 // Rust 1.82.0. 5 // 6 // Permission is hereby granted, free of charge, to any 7 // person obtaining a copy of this software and associated 8 // documentation files (the "Software"), to deal in the 9 // Software without restriction, including without 10 // limitation the rights to use, copy, modify, merge, 11 // publish, distribute, sublicense, and/or sell copies of 12 // the Software, and to permit persons to whom the Software 13 // is furnished to do so, subject to the following 14 // conditions: 15 // 16 // The above copyright notice and this permission notice 17 // shall be included in all copies or substantial portions 18 // of the Software. 19 // 20 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF 21 // ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 22 // TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 23 // PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 24 // SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 25 // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 26 // OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR 27 // IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 28 // DEALINGS IN THE SOFTWARE. 29 30 //! QEMU-specific mutable containers 31 //! 32 //! Rust memory safety is based on this rule: Given an object `T`, it is only 33 //! possible to have one of the following: 34 //! 35 //! - Having several immutable references (`&T`) to the object (also known as 36 //! **aliasing**). 37 //! - Having one mutable reference (`&mut T`) to the object (also known as 38 //! **mutability**). 39 //! 40 //! This is enforced by the Rust compiler. However, there are situations where 41 //! this rule is not flexible enough. Sometimes it is required to have multiple 42 //! references to an object and yet mutate it. In particular, QEMU objects 43 //! usually have their pointer shared with the "outside world very early in 44 //! their lifetime", for example when they create their 45 //! [`MemoryRegion`s](crate::bindings::MemoryRegion). Therefore, individual 46 //! parts of a device must be made mutable in a controlled manner; this module 47 //! provides the tools to do so. 48 //! 49 //! ## Cell types 50 //! 51 //! [`BqlCell<T>`] and [`BqlRefCell<T>`] allow doing this via the Big QEMU Lock. 52 //! While they are essentially the same single-threaded primitives that are 53 //! available in `std::cell`, the BQL allows them to be used from a 54 //! multi-threaded context and to share references across threads, while 55 //! maintaining Rust's safety guarantees. For this reason, unlike 56 //! their `std::cell` counterparts, `BqlCell` and `BqlRefCell` implement the 57 //! `Sync` trait. 58 //! 59 //! BQL checks are performed in debug builds but can be optimized away in 60 //! release builds, providing runtime safety during development with no overhead 61 //! in production. 62 //! 63 //! The two provide different ways of handling interior mutability. 64 //! `BqlRefCell` is best suited for data that is primarily accessed by the 65 //! device's own methods, where multiple reads and writes can be grouped within 66 //! a single borrow and a mutable reference can be passed around. Instead, 67 //! [`BqlCell`] is a better choice when sharing small pieces of data with 68 //! external code (especially C code), because it provides simple get/set 69 //! operations that can be used one at a time. 70 //! 71 //! Warning: While `BqlCell` and `BqlRefCell` are similar to their `std::cell` 72 //! counterparts, they are not interchangeable. Using `std::cell` types in 73 //! QEMU device implementations is usually incorrect and can lead to 74 //! thread-safety issues. 75 //! 76 //! ### Example 77 //! 78 //! ``` 79 //! # use qemu_api::prelude::*; 80 //! # use qemu_api::{cell::BqlRefCell, irq::InterruptSource, irq::IRQState}; 81 //! # use qemu_api::{sysbus::SysBusDevice, qom::Owned, qom::ParentField}; 82 //! # const N_GPIOS: usize = 8; 83 //! # struct PL061Registers { /* ... */ } 84 //! # unsafe impl ObjectType for PL061State { 85 //! # type Class = <SysBusDevice as ObjectType>::Class; 86 //! # const TYPE_NAME: &'static std::ffi::CStr = c"pl061"; 87 //! # } 88 //! struct PL061State { 89 //! parent_obj: ParentField<SysBusDevice>, 90 //! 91 //! // Configuration is read-only after initialization 92 //! pullups: u32, 93 //! pulldowns: u32, 94 //! 95 //! // Single values shared with C code use BqlCell, in this case via InterruptSource 96 //! out: [InterruptSource; N_GPIOS], 97 //! interrupt: InterruptSource, 98 //! 99 //! // Larger state accessed by device methods uses BqlRefCell or Mutex 100 //! registers: BqlRefCell<PL061Registers>, 101 //! } 102 //! ``` 103 //! 104 //! ### `BqlCell<T>` 105 //! 106 //! [`BqlCell<T>`] implements interior mutability by moving values in and out of 107 //! the cell. That is, an `&mut T` to the inner value can never be obtained as 108 //! long as the cell is shared. The value itself cannot be directly obtained 109 //! without copying it, cloning it, or replacing it with something else. This 110 //! type provides the following methods, all of which can be called only while 111 //! the BQL is held: 112 //! 113 //! - For types that implement [`Copy`], the [`get`](BqlCell::get) method 114 //! retrieves the current interior value by duplicating it. 115 //! - For types that implement [`Default`], the [`take`](BqlCell::take) method 116 //! replaces the current interior value with [`Default::default()`] and 117 //! returns the replaced value. 118 //! - All types have: 119 //! - [`replace`](BqlCell::replace): replaces the current interior value and 120 //! returns the replaced value. 121 //! - [`set`](BqlCell::set): this method replaces the interior value, 122 //! dropping the replaced value. 123 //! 124 //! ### `BqlRefCell<T>` 125 //! 126 //! [`BqlRefCell<T>`] uses Rust's lifetimes to implement "dynamic borrowing", a 127 //! process whereby one can claim temporary, exclusive, mutable access to the 128 //! inner value: 129 //! 130 //! ```ignore 131 //! fn clear_interrupts(&self, val: u32) { 132 //! // A mutable borrow gives read-write access to the registers 133 //! let mut regs = self.registers.borrow_mut(); 134 //! let old = regs.interrupt_status(); 135 //! regs.update_interrupt_status(old & !val); 136 //! } 137 //! ``` 138 //! 139 //! Borrows for `BqlRefCell<T>`s are tracked at _runtime_, unlike Rust's native 140 //! reference types which are entirely tracked statically, at compile time. 141 //! Multiple immutable borrows are allowed via [`borrow`](BqlRefCell::borrow), 142 //! or a single mutable borrow via [`borrow_mut`](BqlRefCell::borrow_mut). The 143 //! thread will panic if these rules are violated or if the BQL is not held. 144 //! 145 //! ## Opaque wrappers 146 //! 147 //! The cell types from the previous section are useful at the boundaries 148 //! of code that requires interior mutability. When writing glue code that 149 //! interacts directly with C structs, however, it is useful to operate 150 //! at a lower level. 151 //! 152 //! C functions often violate Rust's fundamental assumptions about memory 153 //! safety by modifying memory even if it is shared. Furthermore, C structs 154 //! often start their life uninitialized and may be populated lazily. 155 //! 156 //! For this reason, this module provides the [`Opaque<T>`] type to opt out 157 //! of Rust's usual guarantees about the wrapped type. Access to the wrapped 158 //! value is always through raw pointers, obtained via methods like 159 //! [`as_mut_ptr()`](Opaque::as_mut_ptr) and [`as_ptr()`](Opaque::as_ptr). These 160 //! pointers can then be passed to C functions or dereferenced; both actions 161 //! require `unsafe` blocks, making it clear where safety guarantees must be 162 //! manually verified. For example 163 //! 164 //! ```ignore 165 //! unsafe { 166 //! let state = Opaque::<MyStruct>::uninit(); 167 //! qemu_struct_init(state.as_mut_ptr()); 168 //! } 169 //! ``` 170 //! 171 //! [`Opaque<T>`] will usually be wrapped one level further, so that 172 //! bridge methods can be added to the wrapper: 173 //! 174 //! ```ignore 175 //! pub struct MyStruct(Opaque<bindings::MyStruct>); 176 //! 177 //! impl MyStruct { 178 //! fn new() -> Pin<Box<MyStruct>> { 179 //! let result = Box::pin(unsafe { Opaque::uninit() }); 180 //! unsafe { qemu_struct_init(result.as_mut_ptr()) }; 181 //! result 182 //! } 183 //! } 184 //! ``` 185 //! 186 //! This pattern of wrapping bindgen-generated types in [`Opaque<T>`] provides 187 //! several advantages: 188 //! 189 //! * The choice of traits to be implemented is not limited by the 190 //! bindgen-generated code. For example, [`Drop`] can be added without 191 //! disabling [`Copy`] on the underlying bindgen type 192 //! 193 //! * [`Send`] and [`Sync`] implementations can be controlled by the wrapper 194 //! type rather than being automatically derived from the C struct's layout 195 //! 196 //! * Methods can be implemented in a separate crate from the bindgen-generated 197 //! bindings 198 //! 199 //! * [`Debug`](std::fmt::Debug) and [`Display`](std::fmt::Display) 200 //! implementations can be customized to be more readable than the raw C 201 //! struct representation 202 //! 203 //! The [`Opaque<T>`] type does not include BQL validation; it is possible to 204 //! assert in the code that the right lock is taken, to use it together 205 //! with a custom lock guard type, or to let C code take the lock, as 206 //! appropriate. It is also possible to use it with non-thread-safe 207 //! types, since by default (unlike [`BqlCell`] and [`BqlRefCell`] 208 //! it is neither `Sync` nor `Send`. 209 //! 210 //! While [`Opaque<T>`] is necessary for C interop, it should be used sparingly 211 //! and only at FFI boundaries. For QEMU-specific types that need interior 212 //! mutability, prefer [`BqlCell`] or [`BqlRefCell`]. 213 214 use std::{ 215 cell::{Cell, UnsafeCell}, 216 cmp::Ordering, 217 fmt, 218 marker::{PhantomData, PhantomPinned}, 219 mem::{self, MaybeUninit}, 220 ops::{Deref, DerefMut}, 221 ptr::NonNull, 222 }; 223 224 use crate::bindings; 225 226 /// An internal function that is used by doctests. 227 pub fn bql_start_test() { 228 // SAFETY: integration tests are run with --test-threads=1, while 229 // unit tests and doctests are not multithreaded and do not have 230 // any BQL-protected data. Just set bql_locked to true. 231 unsafe { 232 bindings::rust_bql_mock_lock(); 233 } 234 } 235 236 pub fn bql_locked() -> bool { 237 // SAFETY: the function does nothing but return a thread-local bool 238 unsafe { bindings::bql_locked() } 239 } 240 241 fn bql_block_unlock(increase: bool) { 242 // SAFETY: this only adjusts a counter 243 unsafe { 244 bindings::bql_block_unlock(increase); 245 } 246 } 247 248 /// A mutable memory location that is protected by the Big QEMU Lock. 249 /// 250 /// # Memory layout 251 /// 252 /// `BqlCell<T>` has the same in-memory representation as its inner type `T`. 253 #[repr(transparent)] 254 pub struct BqlCell<T> { 255 value: UnsafeCell<T>, 256 } 257 258 // SAFETY: Same as for std::sync::Mutex. In the end this *is* a Mutex, 259 // except it is stored out-of-line 260 unsafe impl<T: Send> Send for BqlCell<T> {} 261 unsafe impl<T: Send> Sync for BqlCell<T> {} 262 263 impl<T: Copy> Clone for BqlCell<T> { 264 #[inline] 265 fn clone(&self) -> BqlCell<T> { 266 BqlCell::new(self.get()) 267 } 268 } 269 270 impl<T: Default> Default for BqlCell<T> { 271 /// Creates a `BqlCell<T>`, with the `Default` value for T. 272 #[inline] 273 fn default() -> BqlCell<T> { 274 BqlCell::new(Default::default()) 275 } 276 } 277 278 impl<T: PartialEq + Copy> PartialEq for BqlCell<T> { 279 #[inline] 280 fn eq(&self, other: &BqlCell<T>) -> bool { 281 self.get() == other.get() 282 } 283 } 284 285 impl<T: Eq + Copy> Eq for BqlCell<T> {} 286 287 impl<T: PartialOrd + Copy> PartialOrd for BqlCell<T> { 288 #[inline] 289 fn partial_cmp(&self, other: &BqlCell<T>) -> Option<Ordering> { 290 self.get().partial_cmp(&other.get()) 291 } 292 } 293 294 impl<T: Ord + Copy> Ord for BqlCell<T> { 295 #[inline] 296 fn cmp(&self, other: &BqlCell<T>) -> Ordering { 297 self.get().cmp(&other.get()) 298 } 299 } 300 301 impl<T> From<T> for BqlCell<T> { 302 /// Creates a new `BqlCell<T>` containing the given value. 303 fn from(t: T) -> BqlCell<T> { 304 BqlCell::new(t) 305 } 306 } 307 308 impl<T: fmt::Debug + Copy> fmt::Debug for BqlCell<T> { 309 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 310 self.get().fmt(f) 311 } 312 } 313 314 impl<T: fmt::Display + Copy> fmt::Display for BqlCell<T> { 315 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 316 self.get().fmt(f) 317 } 318 } 319 320 impl<T> BqlCell<T> { 321 /// Creates a new `BqlCell` containing the given value. 322 /// 323 /// # Examples 324 /// 325 /// ``` 326 /// use qemu_api::cell::BqlCell; 327 /// # qemu_api::cell::bql_start_test(); 328 /// 329 /// let c = BqlCell::new(5); 330 /// ``` 331 #[inline] 332 pub const fn new(value: T) -> BqlCell<T> { 333 BqlCell { 334 value: UnsafeCell::new(value), 335 } 336 } 337 338 /// Sets the contained value. 339 /// 340 /// # Examples 341 /// 342 /// ``` 343 /// use qemu_api::cell::BqlCell; 344 /// # qemu_api::cell::bql_start_test(); 345 /// 346 /// let c = BqlCell::new(5); 347 /// 348 /// c.set(10); 349 /// ``` 350 #[inline] 351 pub fn set(&self, val: T) { 352 self.replace(val); 353 } 354 355 /// Replaces the contained value with `val`, and returns the old contained 356 /// value. 357 /// 358 /// # Examples 359 /// 360 /// ``` 361 /// use qemu_api::cell::BqlCell; 362 /// # qemu_api::cell::bql_start_test(); 363 /// 364 /// let cell = BqlCell::new(5); 365 /// assert_eq!(cell.get(), 5); 366 /// assert_eq!(cell.replace(10), 5); 367 /// assert_eq!(cell.get(), 10); 368 /// ``` 369 #[inline] 370 pub fn replace(&self, val: T) -> T { 371 assert!(bql_locked()); 372 // SAFETY: This can cause data races if called from multiple threads, 373 // but it won't happen as long as C code accesses the value 374 // under BQL protection only. 375 mem::replace(unsafe { &mut *self.value.get() }, val) 376 } 377 378 /// Unwraps the value, consuming the cell. 379 /// 380 /// # Examples 381 /// 382 /// ``` 383 /// use qemu_api::cell::BqlCell; 384 /// # qemu_api::cell::bql_start_test(); 385 /// 386 /// let c = BqlCell::new(5); 387 /// let five = c.into_inner(); 388 /// 389 /// assert_eq!(five, 5); 390 /// ``` 391 pub fn into_inner(self) -> T { 392 assert!(bql_locked()); 393 self.value.into_inner() 394 } 395 } 396 397 impl<T: Copy> BqlCell<T> { 398 /// Returns a copy of the contained value. 399 /// 400 /// # Examples 401 /// 402 /// ``` 403 /// use qemu_api::cell::BqlCell; 404 /// # qemu_api::cell::bql_start_test(); 405 /// 406 /// let c = BqlCell::new(5); 407 /// 408 /// let five = c.get(); 409 /// ``` 410 #[inline] 411 pub fn get(&self) -> T { 412 assert!(bql_locked()); 413 // SAFETY: This can cause data races if called from multiple threads, 414 // but it won't happen as long as C code accesses the value 415 // under BQL protection only. 416 unsafe { *self.value.get() } 417 } 418 } 419 420 impl<T> BqlCell<T> { 421 /// Returns a raw pointer to the underlying data in this cell. 422 /// 423 /// # Examples 424 /// 425 /// ``` 426 /// use qemu_api::cell::BqlCell; 427 /// # qemu_api::cell::bql_start_test(); 428 /// 429 /// let c = BqlCell::new(5); 430 /// 431 /// let ptr = c.as_ptr(); 432 /// ``` 433 #[inline] 434 pub const fn as_ptr(&self) -> *mut T { 435 self.value.get() 436 } 437 } 438 439 impl<T: Default> BqlCell<T> { 440 /// Takes the value of the cell, leaving `Default::default()` in its place. 441 /// 442 /// # Examples 443 /// 444 /// ``` 445 /// use qemu_api::cell::BqlCell; 446 /// # qemu_api::cell::bql_start_test(); 447 /// 448 /// let c = BqlCell::new(5); 449 /// let five = c.take(); 450 /// 451 /// assert_eq!(five, 5); 452 /// assert_eq!(c.into_inner(), 0); 453 /// ``` 454 pub fn take(&self) -> T { 455 self.replace(Default::default()) 456 } 457 } 458 459 /// A mutable memory location with dynamically checked borrow rules, 460 /// protected by the Big QEMU Lock. 461 /// 462 /// See the [module-level documentation](self) for more. 463 /// 464 /// # Memory layout 465 /// 466 /// `BqlRefCell<T>` starts with the same in-memory representation as its 467 /// inner type `T`. 468 #[repr(C)] 469 pub struct BqlRefCell<T> { 470 // It is important that this is the first field (which is not the case 471 // for std::cell::BqlRefCell), so that we can use offset_of! on it. 472 // UnsafeCell and repr(C) both prevent usage of niches. 473 value: UnsafeCell<T>, 474 borrow: Cell<BorrowFlag>, 475 // Stores the location of the earliest currently active borrow. 476 // This gets updated whenever we go from having zero borrows 477 // to having a single borrow. When a borrow occurs, this gets included 478 // in the panic message 479 #[cfg(feature = "debug_cell")] 480 borrowed_at: Cell<Option<&'static std::panic::Location<'static>>>, 481 } 482 483 // Positive values represent the number of `BqlRef` active. Negative values 484 // represent the number of `BqlRefMut` active. Right now QEMU's implementation 485 // does not allow to create `BqlRefMut`s that refer to distinct, nonoverlapping 486 // components of a `BqlRefCell` (e.g., different ranges of a slice). 487 // 488 // `BqlRef` and `BqlRefMut` are both two words in size, and so there will likely 489 // never be enough `BqlRef`s or `BqlRefMut`s in existence to overflow half of 490 // the `usize` range. Thus, a `BorrowFlag` will probably never overflow or 491 // underflow. However, this is not a guarantee, as a pathological program could 492 // repeatedly create and then mem::forget `BqlRef`s or `BqlRefMut`s. Thus, all 493 // code must explicitly check for overflow and underflow in order to avoid 494 // unsafety, or at least behave correctly in the event that overflow or 495 // underflow happens (e.g., see BorrowRef::new). 496 type BorrowFlag = isize; 497 const UNUSED: BorrowFlag = 0; 498 499 #[inline(always)] 500 const fn is_writing(x: BorrowFlag) -> bool { 501 x < UNUSED 502 } 503 504 #[inline(always)] 505 const fn is_reading(x: BorrowFlag) -> bool { 506 x > UNUSED 507 } 508 509 impl<T> BqlRefCell<T> { 510 /// Creates a new `BqlRefCell` containing `value`. 511 /// 512 /// # Examples 513 /// 514 /// ``` 515 /// use qemu_api::cell::BqlRefCell; 516 /// 517 /// let c = BqlRefCell::new(5); 518 /// ``` 519 #[inline] 520 pub const fn new(value: T) -> BqlRefCell<T> { 521 BqlRefCell { 522 value: UnsafeCell::new(value), 523 borrow: Cell::new(UNUSED), 524 #[cfg(feature = "debug_cell")] 525 borrowed_at: Cell::new(None), 526 } 527 } 528 } 529 530 // This ensures the panicking code is outlined from `borrow_mut` for 531 // `BqlRefCell`. 532 #[inline(never)] 533 #[cold] 534 #[cfg(feature = "debug_cell")] 535 fn panic_already_borrowed(source: &Cell<Option<&'static std::panic::Location<'static>>>) -> ! { 536 // If a borrow occurred, then we must already have an outstanding borrow, 537 // so `borrowed_at` will be `Some` 538 panic!("already borrowed at {:?}", source.take().unwrap()) 539 } 540 541 #[inline(never)] 542 #[cold] 543 #[cfg(not(feature = "debug_cell"))] 544 fn panic_already_borrowed() -> ! { 545 panic!("already borrowed") 546 } 547 548 impl<T> BqlRefCell<T> { 549 #[inline] 550 #[allow(clippy::unused_self)] 551 fn panic_already_borrowed(&self) -> ! { 552 #[cfg(feature = "debug_cell")] 553 { 554 panic_already_borrowed(&self.borrowed_at) 555 } 556 #[cfg(not(feature = "debug_cell"))] 557 { 558 panic_already_borrowed() 559 } 560 } 561 562 /// Immutably borrows the wrapped value. 563 /// 564 /// The borrow lasts until the returned `BqlRef` exits scope. Multiple 565 /// immutable borrows can be taken out at the same time. 566 /// 567 /// # Panics 568 /// 569 /// Panics if the value is currently mutably borrowed. 570 /// 571 /// # Examples 572 /// 573 /// ``` 574 /// use qemu_api::cell::BqlRefCell; 575 /// # qemu_api::cell::bql_start_test(); 576 /// 577 /// let c = BqlRefCell::new(5); 578 /// 579 /// let borrowed_five = c.borrow(); 580 /// let borrowed_five2 = c.borrow(); 581 /// ``` 582 /// 583 /// An example of panic: 584 /// 585 /// ```should_panic 586 /// use qemu_api::cell::BqlRefCell; 587 /// # qemu_api::cell::bql_start_test(); 588 /// 589 /// let c = BqlRefCell::new(5); 590 /// 591 /// let m = c.borrow_mut(); 592 /// let b = c.borrow(); // this causes a panic 593 /// ``` 594 #[inline] 595 #[track_caller] 596 pub fn borrow(&self) -> BqlRef<'_, T> { 597 if let Some(b) = BorrowRef::new(&self.borrow) { 598 // `borrowed_at` is always the *first* active borrow 599 if b.borrow.get() == 1 { 600 #[cfg(feature = "debug_cell")] 601 self.borrowed_at.set(Some(std::panic::Location::caller())); 602 } 603 604 bql_block_unlock(true); 605 606 // SAFETY: `BorrowRef` ensures that there is only immutable access 607 // to the value while borrowed. 608 let value = unsafe { NonNull::new_unchecked(self.value.get()) }; 609 BqlRef { value, borrow: b } 610 } else { 611 self.panic_already_borrowed() 612 } 613 } 614 615 /// Mutably borrows the wrapped value. 616 /// 617 /// The borrow lasts until the returned `BqlRefMut` or all `BqlRefMut`s 618 /// derived from it exit scope. The value cannot be borrowed while this 619 /// borrow is active. 620 /// 621 /// # Panics 622 /// 623 /// Panics if the value is currently borrowed. 624 /// 625 /// # Examples 626 /// 627 /// ``` 628 /// use qemu_api::cell::BqlRefCell; 629 /// # qemu_api::cell::bql_start_test(); 630 /// 631 /// let c = BqlRefCell::new("hello".to_owned()); 632 /// 633 /// *c.borrow_mut() = "bonjour".to_owned(); 634 /// 635 /// assert_eq!(&*c.borrow(), "bonjour"); 636 /// ``` 637 /// 638 /// An example of panic: 639 /// 640 /// ```should_panic 641 /// use qemu_api::cell::BqlRefCell; 642 /// # qemu_api::cell::bql_start_test(); 643 /// 644 /// let c = BqlRefCell::new(5); 645 /// let m = c.borrow(); 646 /// 647 /// let b = c.borrow_mut(); // this causes a panic 648 /// ``` 649 #[inline] 650 #[track_caller] 651 pub fn borrow_mut(&self) -> BqlRefMut<'_, T> { 652 if let Some(b) = BorrowRefMut::new(&self.borrow) { 653 #[cfg(feature = "debug_cell")] 654 { 655 self.borrowed_at.set(Some(std::panic::Location::caller())); 656 } 657 658 // SAFETY: this only adjusts a counter 659 bql_block_unlock(true); 660 661 // SAFETY: `BorrowRefMut` guarantees unique access. 662 let value = unsafe { NonNull::new_unchecked(self.value.get()) }; 663 BqlRefMut { 664 value, 665 _borrow: b, 666 marker: PhantomData, 667 } 668 } else { 669 self.panic_already_borrowed() 670 } 671 } 672 673 /// Returns a raw pointer to the underlying data in this cell. 674 /// 675 /// # Examples 676 /// 677 /// ``` 678 /// use qemu_api::cell::BqlRefCell; 679 /// 680 /// let c = BqlRefCell::new(5); 681 /// 682 /// let ptr = c.as_ptr(); 683 /// ``` 684 #[inline] 685 pub const fn as_ptr(&self) -> *mut T { 686 self.value.get() 687 } 688 } 689 690 // SAFETY: Same as for std::sync::Mutex. In the end this is a Mutex that is 691 // stored out-of-line. Even though BqlRefCell includes Cells, they are 692 // themselves protected by the Big QEMU Lock. Furtheremore, the Big QEMU 693 // Lock cannot be released while any borrows is active. 694 unsafe impl<T> Send for BqlRefCell<T> where T: Send {} 695 unsafe impl<T> Sync for BqlRefCell<T> {} 696 697 impl<T: Clone> Clone for BqlRefCell<T> { 698 /// # Panics 699 /// 700 /// Panics if the value is currently mutably borrowed. 701 #[inline] 702 #[track_caller] 703 fn clone(&self) -> BqlRefCell<T> { 704 BqlRefCell::new(self.borrow().clone()) 705 } 706 707 /// # Panics 708 /// 709 /// Panics if `source` is currently mutably borrowed. 710 #[inline] 711 #[track_caller] 712 fn clone_from(&mut self, source: &Self) { 713 self.value.get_mut().clone_from(&source.borrow()) 714 } 715 } 716 717 impl<T: Default> Default for BqlRefCell<T> { 718 /// Creates a `BqlRefCell<T>`, with the `Default` value for T. 719 #[inline] 720 fn default() -> BqlRefCell<T> { 721 BqlRefCell::new(Default::default()) 722 } 723 } 724 725 impl<T: PartialEq> PartialEq for BqlRefCell<T> { 726 /// # Panics 727 /// 728 /// Panics if the value in either `BqlRefCell` is currently mutably 729 /// borrowed. 730 #[inline] 731 fn eq(&self, other: &BqlRefCell<T>) -> bool { 732 *self.borrow() == *other.borrow() 733 } 734 } 735 736 impl<T: Eq> Eq for BqlRefCell<T> {} 737 738 impl<T: PartialOrd> PartialOrd for BqlRefCell<T> { 739 /// # Panics 740 /// 741 /// Panics if the value in either `BqlRefCell` is currently mutably 742 /// borrowed. 743 #[inline] 744 fn partial_cmp(&self, other: &BqlRefCell<T>) -> Option<Ordering> { 745 self.borrow().partial_cmp(&*other.borrow()) 746 } 747 } 748 749 impl<T: Ord> Ord for BqlRefCell<T> { 750 /// # Panics 751 /// 752 /// Panics if the value in either `BqlRefCell` is currently mutably 753 /// borrowed. 754 #[inline] 755 fn cmp(&self, other: &BqlRefCell<T>) -> Ordering { 756 self.borrow().cmp(&*other.borrow()) 757 } 758 } 759 760 impl<T> From<T> for BqlRefCell<T> { 761 /// Creates a new `BqlRefCell<T>` containing the given value. 762 fn from(t: T) -> BqlRefCell<T> { 763 BqlRefCell::new(t) 764 } 765 } 766 767 struct BorrowRef<'b> { 768 borrow: &'b Cell<BorrowFlag>, 769 } 770 771 impl<'b> BorrowRef<'b> { 772 #[inline] 773 fn new(borrow: &'b Cell<BorrowFlag>) -> Option<BorrowRef<'b>> { 774 let b = borrow.get().wrapping_add(1); 775 if !is_reading(b) { 776 // Incrementing borrow can result in a non-reading value (<= 0) in these cases: 777 // 1. It was < 0, i.e. there are writing borrows, so we can't allow a read 778 // borrow due to Rust's reference aliasing rules 779 // 2. It was isize::MAX (the max amount of reading borrows) and it overflowed 780 // into isize::MIN (the max amount of writing borrows) so we can't allow an 781 // additional read borrow because isize can't represent so many read borrows 782 // (this can only happen if you mem::forget more than a small constant amount 783 // of `BqlRef`s, which is not good practice) 784 None 785 } else { 786 // Incrementing borrow can result in a reading value (> 0) in these cases: 787 // 1. It was = 0, i.e. it wasn't borrowed, and we are taking the first read 788 // borrow 789 // 2. It was > 0 and < isize::MAX, i.e. there were read borrows, and isize is 790 // large enough to represent having one more read borrow 791 borrow.set(b); 792 Some(BorrowRef { borrow }) 793 } 794 } 795 } 796 797 impl Drop for BorrowRef<'_> { 798 #[inline] 799 fn drop(&mut self) { 800 let borrow = self.borrow.get(); 801 debug_assert!(is_reading(borrow)); 802 self.borrow.set(borrow - 1); 803 bql_block_unlock(false) 804 } 805 } 806 807 impl Clone for BorrowRef<'_> { 808 #[inline] 809 fn clone(&self) -> Self { 810 BorrowRef::new(self.borrow).unwrap() 811 } 812 } 813 814 /// Wraps a borrowed reference to a value in a `BqlRefCell` box. 815 /// A wrapper type for an immutably borrowed value from a `BqlRefCell<T>`. 816 /// 817 /// See the [module-level documentation](self) for more. 818 pub struct BqlRef<'b, T: 'b> { 819 // NB: we use a pointer instead of `&'b T` to avoid `noalias` violations, because a 820 // `BqlRef` argument doesn't hold immutability for its whole scope, only until it drops. 821 // `NonNull` is also covariant over `T`, just like we would have with `&T`. 822 value: NonNull<T>, 823 borrow: BorrowRef<'b>, 824 } 825 826 impl<T> Deref for BqlRef<'_, T> { 827 type Target = T; 828 829 #[inline] 830 fn deref(&self) -> &T { 831 // SAFETY: the value is accessible as long as we hold our borrow. 832 unsafe { self.value.as_ref() } 833 } 834 } 835 836 impl<'b, T> BqlRef<'b, T> { 837 /// Copies a `BqlRef`. 838 /// 839 /// The `BqlRefCell` is already immutably borrowed, so this cannot fail. 840 /// 841 /// This is an associated function that needs to be used as 842 /// `BqlRef::clone(...)`. A `Clone` implementation or a method would 843 /// interfere with the widespread use of `r.borrow().clone()` to clone 844 /// the contents of a `BqlRefCell`. 845 #[must_use] 846 #[inline] 847 #[allow(clippy::should_implement_trait)] 848 pub fn clone(orig: &BqlRef<'b, T>) -> BqlRef<'b, T> { 849 BqlRef { 850 value: orig.value, 851 borrow: orig.borrow.clone(), 852 } 853 } 854 } 855 856 impl<T: fmt::Debug> fmt::Debug for BqlRef<'_, T> { 857 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 858 (**self).fmt(f) 859 } 860 } 861 862 impl<T: fmt::Display> fmt::Display for BqlRef<'_, T> { 863 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 864 (**self).fmt(f) 865 } 866 } 867 868 struct BorrowRefMut<'b> { 869 borrow: &'b Cell<BorrowFlag>, 870 } 871 872 impl<'b> BorrowRefMut<'b> { 873 #[inline] 874 fn new(borrow: &'b Cell<BorrowFlag>) -> Option<BorrowRefMut<'b>> { 875 // There must currently be no existing references when borrow_mut() is 876 // called, so we explicitly only allow going from UNUSED to UNUSED - 1. 877 match borrow.get() { 878 UNUSED => { 879 borrow.set(UNUSED - 1); 880 Some(BorrowRefMut { borrow }) 881 } 882 _ => None, 883 } 884 } 885 } 886 887 impl Drop for BorrowRefMut<'_> { 888 #[inline] 889 fn drop(&mut self) { 890 let borrow = self.borrow.get(); 891 debug_assert!(is_writing(borrow)); 892 self.borrow.set(borrow + 1); 893 bql_block_unlock(false) 894 } 895 } 896 897 /// A wrapper type for a mutably borrowed value from a `BqlRefCell<T>`. 898 /// 899 /// See the [module-level documentation](self) for more. 900 pub struct BqlRefMut<'b, T: 'b> { 901 // NB: we use a pointer instead of `&'b mut T` to avoid `noalias` violations, because a 902 // `BqlRefMut` argument doesn't hold exclusivity for its whole scope, only until it drops. 903 value: NonNull<T>, 904 _borrow: BorrowRefMut<'b>, 905 // `NonNull` is covariant over `T`, so we need to reintroduce invariance. 906 marker: PhantomData<&'b mut T>, 907 } 908 909 impl<T> Deref for BqlRefMut<'_, T> { 910 type Target = T; 911 912 #[inline] 913 fn deref(&self) -> &T { 914 // SAFETY: the value is accessible as long as we hold our borrow. 915 unsafe { self.value.as_ref() } 916 } 917 } 918 919 impl<T> DerefMut for BqlRefMut<'_, T> { 920 #[inline] 921 fn deref_mut(&mut self) -> &mut T { 922 // SAFETY: the value is accessible as long as we hold our borrow. 923 unsafe { self.value.as_mut() } 924 } 925 } 926 927 impl<T: fmt::Debug> fmt::Debug for BqlRefMut<'_, T> { 928 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 929 (**self).fmt(f) 930 } 931 } 932 933 impl<T: fmt::Display> fmt::Display for BqlRefMut<'_, T> { 934 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 935 (**self).fmt(f) 936 } 937 } 938 939 /// Stores an opaque value that is shared with C code. 940 /// 941 /// Often, C structs can changed when calling a C function even if they are 942 /// behind a shared Rust reference, or they can be initialized lazily and have 943 /// invalid bit patterns (e.g. `3` for a [`bool`]). This goes against Rust's 944 /// strict aliasing rules, which normally prevent mutation through shared 945 /// references. 946 /// 947 /// Wrapping the struct with `Opaque<T>` ensures that the Rust compiler does not 948 /// assume the usual constraints that Rust structs require, and allows using 949 /// shared references on the Rust side. 950 /// 951 /// `Opaque<T>` is `#[repr(transparent)]`, so that it matches the memory layout 952 /// of `T`. 953 #[repr(transparent)] 954 pub struct Opaque<T> { 955 value: UnsafeCell<MaybeUninit<T>>, 956 // PhantomPinned also allows multiple references to the `Opaque<T>`, i.e. 957 // one `&mut Opaque<T>` can coexist with a `&mut T` or any number of `&T`; 958 // see https://docs.rs/pinned-aliasable/latest/pinned_aliasable/. 959 _pin: PhantomPinned, 960 } 961 962 impl<T> Opaque<T> { 963 /// Creates a new shared reference from a C pointer 964 /// 965 /// # Safety 966 /// 967 /// The pointer must be valid, though it need not point to a valid value. 968 pub unsafe fn from_raw<'a>(ptr: *mut T) -> &'a Self { 969 let ptr = NonNull::new(ptr).unwrap().cast::<Self>(); 970 // SAFETY: Self is a transparent wrapper over T 971 unsafe { ptr.as_ref() } 972 } 973 974 /// Creates a new opaque object with uninitialized contents. 975 /// 976 /// # Safety 977 /// 978 /// Ultimately the pointer to the returned value will be dereferenced 979 /// in another `unsafe` block, for example when passing it to a C function, 980 /// but the functions containing the dereference are usually safe. The 981 /// value returned from `uninit()` must be initialized and pinned before 982 /// calling them. 983 #[allow(clippy::missing_const_for_fn)] 984 pub unsafe fn uninit() -> Self { 985 Self { 986 value: UnsafeCell::new(MaybeUninit::uninit()), 987 _pin: PhantomPinned, 988 } 989 } 990 991 /// Creates a new opaque object with zeroed contents. 992 /// 993 /// # Safety 994 /// 995 /// Ultimately the pointer to the returned value will be dereferenced 996 /// in another `unsafe` block, for example when passing it to a C function, 997 /// but the functions containing the dereference are usually safe. The 998 /// value returned from `uninit()` must be pinned (and possibly initialized) 999 /// before calling them. 1000 #[allow(clippy::missing_const_for_fn)] 1001 pub unsafe fn zeroed() -> Self { 1002 Self { 1003 value: UnsafeCell::new(MaybeUninit::zeroed()), 1004 _pin: PhantomPinned, 1005 } 1006 } 1007 1008 /// Returns a raw mutable pointer to the opaque data. 1009 pub const fn as_mut_ptr(&self) -> *mut T { 1010 UnsafeCell::get(&self.value).cast() 1011 } 1012 1013 /// Returns a raw pointer to the opaque data. 1014 pub const fn as_ptr(&self) -> *const T { 1015 self.as_mut_ptr().cast_const() 1016 } 1017 1018 /// Returns a raw pointer to the opaque data that can be passed to a 1019 /// C function as `void *`. 1020 pub const fn as_void_ptr(&self) -> *mut std::ffi::c_void { 1021 UnsafeCell::get(&self.value).cast() 1022 } 1023 1024 /// Converts a raw pointer to the wrapped type. 1025 pub const fn raw_get(slot: *mut Self) -> *mut T { 1026 // Compare with Linux's raw_get method, which goes through an UnsafeCell 1027 // because it takes a *const Self instead. 1028 slot.cast() 1029 } 1030 } 1031 1032 impl<T> fmt::Debug for Opaque<T> { 1033 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 1034 let mut name: String = "Opaque<".to_string(); 1035 name += std::any::type_name::<T>(); 1036 name += ">"; 1037 f.debug_tuple(&name).field(&self.as_ptr()).finish() 1038 } 1039 } 1040 1041 impl<T: Default> Opaque<T> { 1042 /// Creates a new opaque object with default contents. 1043 /// 1044 /// # Safety 1045 /// 1046 /// Ultimately the pointer to the returned value will be dereferenced 1047 /// in another `unsafe` block, for example when passing it to a C function, 1048 /// but the functions containing the dereference are usually safe. The 1049 /// value returned from `uninit()` must be pinned before calling them. 1050 pub unsafe fn new() -> Self { 1051 Self { 1052 value: UnsafeCell::new(MaybeUninit::new(T::default())), 1053 _pin: PhantomPinned, 1054 } 1055 } 1056 } 1057 1058 /// Annotates [`Self`] as a transparent wrapper for another type. 1059 /// 1060 /// Usually defined via the [`qemu_api_macros::Wrapper`] derive macro. 1061 /// 1062 /// # Examples 1063 /// 1064 /// ``` 1065 /// # use std::mem::ManuallyDrop; 1066 /// # use qemu_api::cell::Wrapper; 1067 /// #[repr(transparent)] 1068 /// pub struct Example { 1069 /// inner: ManuallyDrop<String>, 1070 /// } 1071 /// 1072 /// unsafe impl Wrapper for Example { 1073 /// type Wrapped = String; 1074 /// } 1075 /// ``` 1076 /// 1077 /// # Safety 1078 /// 1079 /// `Self` must be a `#[repr(transparent)]` wrapper for the `Wrapped` type, 1080 /// whether directly or indirectly. 1081 /// 1082 /// # Methods 1083 /// 1084 /// By convention, types that implement Wrapper also implement the following 1085 /// methods: 1086 /// 1087 /// ```ignore 1088 /// pub const unsafe fn from_raw<'a>(value: *mut Self::Wrapped) -> &'a Self; 1089 /// pub const unsafe fn as_mut_ptr(&self) -> *mut Self::Wrapped; 1090 /// pub const unsafe fn as_ptr(&self) -> *const Self::Wrapped; 1091 /// pub const unsafe fn raw_get(slot: *mut Self) -> *const Self::Wrapped; 1092 /// ``` 1093 /// 1094 /// They are not defined here to allow them to be `const`. 1095 pub unsafe trait Wrapper { 1096 type Wrapped; 1097 } 1098 1099 unsafe impl<T> Wrapper for Opaque<T> { 1100 type Wrapped = T; 1101 } 1102