1 // Copyright (C) 2019 Alibaba Cloud. All rights reserved. 2 // Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. 3 // Copyright © 2019 Intel Corporation 4 // 5 // SPDX-License-Identifier: Apache-2.0 OR BSD-3-Clause 6 7 //! Traits and Structs to manage interrupt sources for devices. 8 //! 9 //! In system programming, an interrupt is a signal to the processor emitted by hardware or 10 //! software indicating an event that needs immediate attention. An interrupt alerts the processor 11 //! to a high-priority condition requiring the interruption of the current code the processor is 12 //! executing. The processor responds by suspending its current activities, saving its state, and 13 //! executing a function called an interrupt handler (or an interrupt service routine, ISR) to deal 14 //! with the event. This interruption is temporary, and, after the interrupt handler finishes, 15 //! unless handling the interrupt has emitted a fatal error, the processor resumes normal 16 //! activities. 17 //! 18 //! Hardware interrupts are used by devices to communicate that they require attention from the 19 //! operating system, or a bare-metal program running on the CPU if there are no OSes. The act of 20 //! initiating a hardware interrupt is referred to as an interrupt request (IRQ). Different devices 21 //! are usually associated with different interrupts using a unique value associated with each 22 //! interrupt. This makes it possible to know which hardware device caused which interrupts. 23 //! These interrupt values are often called IRQ lines, or just interrupt lines. 24 //! 25 //! Nowadays, IRQ lines is not the only mechanism to deliver device interrupts to processors. 26 //! MSI [(Message Signaled Interrupt)](https://en.wikipedia.org/wiki/Message_Signaled_Interrupts) 27 //! is another commonly used alternative in-band method of signaling an interrupt, using special 28 //! in-band messages to replace traditional out-of-band assertion of dedicated interrupt lines. 29 //! While more complex to implement in a device, message signaled interrupts have some significant 30 //! advantages over pin-based out-of-band interrupt signaling. Message signaled interrupts are 31 //! supported in PCI bus since its version 2.2, and in later available PCI Express bus. Some 32 //! non-PCI architectures also use message signaled interrupts. 33 //! 34 //! While IRQ is a term commonly used by Operating Systems when dealing with hardware 35 //! interrupts, the IRQ numbers managed by OSes are independent of the ones managed by VMM. 36 //! For simplicity sake, the term `Interrupt Source` is used instead of IRQ to represent both 37 //! pin-based interrupts and MSI interrupts. 38 //! 39 //! A device may support multiple types of interrupts, and each type of interrupt may support one 40 //! or multiple interrupt sources. For example, a PCI device may support: 41 //! * Legacy Irq: exactly one interrupt source. 42 //! * PCI MSI Irq: 1,2,4,8,16,32 interrupt sources. 43 //! * PCI MSIx Irq: 2^n(n=0-11) interrupt sources. 44 //! 45 //! A distinct Interrupt Source Identifier (ISID) will be assigned to each interrupt source. 46 //! An ID allocator will be used to allocate and free Interrupt Source Identifiers for devices. 47 //! To decouple the vm-device crate from the ID allocator, the vm-device crate doesn't take the 48 //! responsibility to allocate/free Interrupt Source IDs but only makes use of assigned IDs. 49 //! 50 //! The overall flow to deal with interrupts is: 51 //! * The VMM creates an interrupt manager 52 //! * The VMM creates a device manager, passing on an reference to the interrupt manager 53 //! * The device manager passes on an reference to the interrupt manager to all registered devices 54 //! * The guest kernel loads drivers for virtual devices 55 //! * The guest device driver determines the type and number of interrupts needed, and update the 56 //! device configuration 57 //! * The virtual device backend requests the interrupt manager to create an interrupt group 58 //! according to guest configuration information 59 60 use std::sync::Arc; 61 use vmm_sys_util::eventfd::EventFd; 62 63 /// Reuse std::io::Result to simplify interoperability among crates. 64 pub type Result<T> = std::io::Result<T>; 65 66 /// Data type to store an interrupt source identifier. 67 pub type InterruptIndex = u32; 68 69 /// Configuration data for legacy interrupts. 70 /// 71 /// On x86 platforms, legacy interrupts means those interrupts routed through PICs or IOAPICs. 72 #[derive(Copy, Clone, Debug)] 73 pub struct LegacyIrqSourceConfig { 74 pub irqchip: u32, 75 pub pin: u32, 76 } 77 78 /// Configuration data for MSI/MSI-X interrupts. 79 /// 80 /// On x86 platforms, these interrupts are vectors delivered directly to the LAPIC. 81 #[derive(Copy, Clone, Debug, Default)] 82 pub struct MsiIrqSourceConfig { 83 /// High address to delivery message signaled interrupt. 84 pub high_addr: u32, 85 /// Low address to delivery message signaled interrupt. 86 pub low_addr: u32, 87 /// Data to write to delivery message signaled interrupt. 88 pub data: u32, 89 /// Unique ID of the device to delivery message signaled interrupt. 90 pub devid: u32, 91 } 92 93 /// Configuration data for an interrupt source. 94 #[derive(Copy, Clone, Debug)] 95 pub enum InterruptSourceConfig { 96 /// Configuration data for Legacy interrupts. 97 LegacyIrq(LegacyIrqSourceConfig), 98 /// Configuration data for PciMsi, PciMsix and generic MSI interrupts. 99 MsiIrq(MsiIrqSourceConfig), 100 } 101 102 /// Configuration data for legacy, pin based interrupt groups. 103 /// 104 /// A legacy interrupt group only takes one irq number as its configuration. 105 #[derive(Copy, Clone, Debug)] 106 pub struct LegacyIrqGroupConfig { 107 /// Legacy irq number. 108 pub irq: InterruptIndex, 109 } 110 111 /// Configuration data for MSI/MSI-X interrupt groups 112 /// 113 /// MSI/MSI-X interrupt groups are basically a set of vectors. 114 #[derive(Copy, Clone, Debug)] 115 pub struct MsiIrqGroupConfig { 116 /// First index of the MSI/MSI-X interrupt vectors 117 pub base: InterruptIndex, 118 /// Number of vectors in the MSI/MSI-X group. 119 pub count: InterruptIndex, 120 } 121 122 /// Trait to manage interrupt sources for virtual device backends. 123 /// 124 /// The InterruptManager implementations should protect itself from concurrent accesses internally, 125 /// so it could be invoked from multi-threaded context. 126 pub trait InterruptManager: Send + Sync { 127 type GroupConfig; 128 129 /// Create an [InterruptSourceGroup](trait.InterruptSourceGroup.html) object to manage 130 /// interrupt sources for a virtual device 131 /// 132 /// An [InterruptSourceGroup](trait.InterruptSourceGroup.html) object manages all interrupt 133 /// sources of the same type for a virtual device. 134 /// 135 /// # Arguments 136 /// * interrupt_type: type of interrupt source. 137 /// * base: base Interrupt Source ID to be managed by the group object. 138 /// * count: number of Interrupt Sources to be managed by the group object. 139 fn create_group(&self, config: Self::GroupConfig) -> Result<Arc<dyn InterruptSourceGroup>>; 140 141 /// Destroy an [InterruptSourceGroup](trait.InterruptSourceGroup.html) object created by 142 /// [create_group()](trait.InterruptManager.html#tymethod.create_group). 143 /// 144 /// Assume the caller takes the responsibility to disable all interrupt sources of the group 145 /// before calling destroy_group(). This assumption helps to simplify InterruptSourceGroup 146 /// implementations. 147 fn destroy_group(&self, group: Arc<dyn InterruptSourceGroup>) -> Result<()>; 148 } 149 150 pub trait InterruptSourceGroup: Send + Sync { 151 /// Enable the interrupt sources in the group to generate interrupts. 152 fn enable(&self) -> Result<()> { 153 // Not all interrupt sources can be enabled. 154 // To accommodate this, we can have a no-op here. 155 Ok(()) 156 } 157 158 /// Disable the interrupt sources in the group to generate interrupts. 159 fn disable(&self) -> Result<()> { 160 // Not all interrupt sources can be disabled. 161 // To accommodate this, we can have a no-op here. 162 Ok(()) 163 } 164 165 /// Inject an interrupt from this interrupt source into the guest. 166 fn trigger(&self, index: InterruptIndex) -> Result<()>; 167 168 /// Returns an interrupt notifier from this interrupt. 169 /// 170 /// An interrupt notifier allows for external components and processes 171 /// to inject interrupts into a guest, by writing to the file returned 172 /// by this method. 173 #[allow(unused_variables)] 174 fn notifier(&self, index: InterruptIndex) -> Option<EventFd>; 175 176 /// Update the interrupt source group configuration. 177 /// 178 /// # Arguments 179 /// * index: sub-index into the group. 180 /// * config: configuration data for the interrupt source. 181 fn update(&self, index: InterruptIndex, config: InterruptSourceConfig) -> Result<()>; 182 183 /// Mask an interrupt from this interrupt source. 184 fn mask(&self, _index: InterruptIndex) -> Result<()> { 185 // Not all interrupt sources can be disabled. 186 // To accommodate this, we can have a no-op here. 187 Ok(()) 188 } 189 190 /// Unmask an interrupt from this interrupt source. 191 fn unmask(&self, _index: InterruptIndex) -> Result<()> { 192 // Not all interrupt sources can be disabled. 193 // To accommodate this, we can have a no-op here. 194 Ok(()) 195 } 196 } 197