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 62 pub use hypervisor::{InterruptSourceConfig, LegacyIrqSourceConfig, MsiIrqSourceConfig}; 63 use vmm_sys_util::eventfd::EventFd; 64 65 /// Reuse std::io::Result to simplify interoperability among crates. 66 pub type Result<T> = std::io::Result<T>; 67 68 /// Data type to store an interrupt source identifier. 69 pub type InterruptIndex = u32; 70 71 /// Configuration data for legacy, pin based interrupt groups. 72 /// 73 /// A legacy interrupt group only takes one irq number as its configuration. 74 #[derive(Copy, Clone, Debug)] 75 pub struct LegacyIrqGroupConfig { 76 /// Legacy irq number. 77 pub irq: InterruptIndex, 78 } 79 80 /// Configuration data for MSI/MSI-X interrupt groups 81 /// 82 /// MSI/MSI-X interrupt groups are basically a set of vectors. 83 #[derive(Copy, Clone, Debug)] 84 pub struct MsiIrqGroupConfig { 85 /// First index of the MSI/MSI-X interrupt vectors 86 pub base: InterruptIndex, 87 /// Number of vectors in the MSI/MSI-X group. 88 pub count: InterruptIndex, 89 } 90 91 /// Trait to manage interrupt sources for virtual device backends. 92 /// 93 /// The InterruptManager implementations should protect itself from concurrent accesses internally, 94 /// so it could be invoked from multi-threaded context. 95 pub trait InterruptManager: Send + Sync { 96 type GroupConfig; 97 98 /// Create an [InterruptSourceGroup](trait.InterruptSourceGroup.html) object to manage 99 /// interrupt sources for a virtual device 100 /// 101 /// An [InterruptSourceGroup](trait.InterruptSourceGroup.html) object manages all interrupt 102 /// sources of the same type for a virtual device. 103 /// 104 /// # Arguments 105 /// * interrupt_type: type of interrupt source. 106 /// * base: base Interrupt Source ID to be managed by the group object. 107 /// * count: number of Interrupt Sources to be managed by the group object. 108 fn create_group(&self, config: Self::GroupConfig) -> Result<Arc<dyn InterruptSourceGroup>>; 109 110 /// Destroy an [InterruptSourceGroup](trait.InterruptSourceGroup.html) object created by 111 /// [create_group()](trait.InterruptManager.html#tymethod.create_group). 112 /// 113 /// Assume the caller takes the responsibility to disable all interrupt sources of the group 114 /// before calling destroy_group(). This assumption helps to simplify InterruptSourceGroup 115 /// implementations. 116 fn destroy_group(&self, group: Arc<dyn InterruptSourceGroup>) -> Result<()>; 117 } 118 119 pub trait InterruptSourceGroup: Send + Sync { 120 /// Enable the interrupt sources in the group to generate interrupts. 121 fn enable(&self) -> Result<()> { 122 // Not all interrupt sources can be enabled. 123 // To accommodate this, we can have a no-op here. 124 Ok(()) 125 } 126 127 /// Disable the interrupt sources in the group to generate interrupts. 128 fn disable(&self) -> Result<()> { 129 // Not all interrupt sources can be disabled. 130 // To accommodate this, we can have a no-op here. 131 Ok(()) 132 } 133 134 /// Inject an interrupt from this interrupt source into the guest. 135 fn trigger(&self, index: InterruptIndex) -> Result<()>; 136 137 /// Returns an interrupt notifier from this interrupt. 138 /// 139 /// An interrupt notifier allows for external components and processes 140 /// to inject interrupts into a guest, by writing to the file returned 141 /// by this method. 142 #[allow(unused_variables)] 143 fn notifier(&self, index: InterruptIndex) -> Option<EventFd>; 144 145 /// Update the interrupt source group configuration. 146 /// 147 /// # Arguments 148 /// * index: sub-index into the group. 149 /// * config: configuration data for the interrupt source. 150 /// * masked: if the interrupt is masked 151 /// * set_gsi: whether update the GSI routing table. 152 fn update( 153 &self, 154 index: InterruptIndex, 155 config: InterruptSourceConfig, 156 masked: bool, 157 set_gsi: bool, 158 ) -> Result<()>; 159 160 /// Set the interrupt group GSI routing table. 161 fn set_gsi(&self) -> Result<()>; 162 } 163