1 // Copyright 2024 Red Hat, Inc. 2 // Author(s): Paolo Bonzini <pbonzini@redhat.com> 3 // SPDX-License-Identifier: GPL-2.0-or-later 4 5 //! Bindings for interrupt sources 6 7 use std::{ffi::CStr, marker::PhantomData, os::raw::c_int, ptr}; 8 9 use crate::{ 10 bindings::{self, qemu_set_irq}, 11 prelude::*, 12 qom::ObjectClass, 13 }; 14 15 /// Interrupt sources are used by devices to pass changes to a value (typically 16 /// a boolean). The interrupt sink is usually an interrupt controller or 17 /// GPIO controller. 18 /// 19 /// As far as devices are concerned, interrupt sources are always active-high: 20 /// for example, `InterruptSource<bool>`'s [`raise`](InterruptSource::raise) 21 /// method sends a `true` value to the sink. If the guest has to see a 22 /// different polarity, that change is performed by the board between the 23 /// device and the interrupt controller. 24 pub type IRQState = bindings::IRQState; 25 26 /// Interrupts are implemented as a pointer to the interrupt "sink", which has 27 /// type [`IRQState`]. A device exposes its source as a QOM link property using 28 /// a function such as [`SysBusDeviceMethods::init_irq`], and 29 /// initially leaves the pointer to a NULL value, representing an unconnected 30 /// interrupt. To connect it, whoever creates the device fills the pointer with 31 /// the sink's `IRQState *`, for example using `sysbus_connect_irq`. Because 32 /// devices are generally shared objects, interrupt sources are an example of 33 /// the interior mutability pattern. 34 /// 35 /// Interrupt sources can only be triggered under the Big QEMU Lock; `BqlCell` 36 /// allows access from whatever thread has it. 37 #[derive(Debug)] 38 #[repr(transparent)] 39 pub struct InterruptSource<T = bool> 40 where 41 c_int: From<T>, 42 { 43 cell: BqlCell<*mut IRQState>, 44 _marker: PhantomData<T>, 45 } 46 47 // SAFETY: the implementation asserts via `BqlCell` that the BQL is taken 48 unsafe impl<T> Sync for InterruptSource<T> where c_int: From<T> {} 49 50 impl InterruptSource<bool> { 51 /// Send a low (`false`) value to the interrupt sink. 52 pub fn lower(&self) { 53 self.set(false); 54 } 55 56 /// Send a high-low pulse to the interrupt sink. 57 pub fn pulse(&self) { 58 self.set(true); 59 self.set(false); 60 } 61 62 /// Send a high (`true`) value to the interrupt sink. 63 pub fn raise(&self) { 64 self.set(true); 65 } 66 } 67 68 impl<T> InterruptSource<T> 69 where 70 c_int: From<T>, 71 { 72 /// Send `level` to the interrupt sink. 73 pub fn set(&self, level: T) { 74 let ptr = self.cell.get(); 75 // SAFETY: the pointer is retrieved under the BQL and remains valid 76 // until the BQL is released, which is after qemu_set_irq() is entered. 77 unsafe { 78 qemu_set_irq(ptr, level.into()); 79 } 80 } 81 82 pub(crate) const fn as_ptr(&self) -> *mut *mut IRQState { 83 self.cell.as_ptr() 84 } 85 86 pub(crate) const fn slice_as_ptr(slice: &[Self]) -> *mut *mut IRQState { 87 assert!(!slice.is_empty()); 88 slice[0].as_ptr() 89 } 90 } 91 92 impl Default for InterruptSource { 93 fn default() -> Self { 94 InterruptSource { 95 cell: BqlCell::new(ptr::null_mut()), 96 _marker: PhantomData, 97 } 98 } 99 } 100 101 unsafe impl ObjectType for IRQState { 102 type Class = ObjectClass; 103 const TYPE_NAME: &'static CStr = 104 unsafe { CStr::from_bytes_with_nul_unchecked(bindings::TYPE_IRQ) }; 105 } 106 qom_isa!(IRQState: Object); 107