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