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 core::ptr; 8 use std::{marker::PhantomData, os::raw::c_int}; 9 10 use crate::{ 11 bindings::{qemu_set_irq, IRQState}, 12 prelude::*, 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 /// 25 /// Interrupts are implemented as a pointer to the interrupt "sink", which has 26 /// type [`IRQState`]. A device exposes its source as a QOM link property using 27 /// a function such as [`SysBusDeviceMethods::init_irq`], and 28 /// initially leaves the pointer to a NULL value, representing an unconnected 29 /// interrupt. To connect it, whoever creates the device fills the pointer with 30 /// the sink's `IRQState *`, for example using `sysbus_connect_irq`. Because 31 /// devices are generally shared objects, interrupt sources are an example of 32 /// the interior mutability pattern. 33 /// 34 /// Interrupt sources can only be triggered under the Big QEMU Lock; `BqlCell` 35 /// allows access from whatever thread has it. 36 #[derive(Debug)] 37 #[repr(transparent)] 38 pub struct InterruptSource<T = bool> 39 where 40 c_int: From<T>, 41 { 42 cell: BqlCell<*mut IRQState>, 43 _marker: PhantomData<T>, 44 } 45 46 // SAFETY: the implementation asserts via `BqlCell` that the BQL is taken 47 unsafe impl<T> Sync for InterruptSource<T> where c_int: From<T> {} 48 49 impl InterruptSource<bool> { 50 /// Send a low (`false`) value to the interrupt sink. 51 pub fn lower(&self) { 52 self.set(false); 53 } 54 55 /// Send a high-low pulse to the interrupt sink. 56 pub fn pulse(&self) { 57 self.set(true); 58 self.set(false); 59 } 60 61 /// Send a high (`true`) value to the interrupt sink. 62 pub fn raise(&self) { 63 self.set(true); 64 } 65 } 66 67 impl<T> InterruptSource<T> 68 where 69 c_int: From<T>, 70 { 71 /// Send `level` to the interrupt sink. 72 pub fn set(&self, level: T) { 73 let ptr = self.cell.get(); 74 // SAFETY: the pointer is retrieved under the BQL and remains valid 75 // until the BQL is released, which is after qemu_set_irq() is entered. 76 unsafe { 77 qemu_set_irq(ptr, level.into()); 78 } 79 } 80 81 pub(crate) const fn as_ptr(&self) -> *mut *mut IRQState { 82 self.cell.as_ptr() 83 } 84 } 85 86 impl Default for InterruptSource { 87 fn default() -> Self { 88 InterruptSource { 89 cell: BqlCell::new(ptr::null_mut()), 90 _marker: PhantomData, 91 } 92 } 93 } 94