interrupt: Add traits for interrupt abstractions.

Add a series of Traits and structs for defining the interface for
interrupts.
The goal is to allow individual development of device crates that can
work with different types of interrupt mechanisms.
The interrupt mechanism can be implemented in the VMM based on the
platform or the available hardware (e.g. CPU, Interrupt controller).
These set of traits allow devices to use a simple interface through
which they can request, release, configure interrupts and also signal
events to the VMM.

Signed-off-by: Alexandru-Cezar Sardan <alsardan@amazon.com>

Author: Alexandru-Cezar Sardan

src/interrupt/legacy.rs

@@ -0,0 +1,39 @@
+// Copyright (C) 2021 Amazon.com, Inc. or its affiliates.
+// All Rights Reserved.
+
+// SPDX-License-Identifier: Apache-2.0 OR BSD-3-Clause
+
+//! Traits and Structs to manage legacy interrupt sources for devices.
+//!
+//! Legacy interrupt sources typically include pin based interrupt lines.
+
+use crate::interrupt::ConfigurableInterrupt;
+
+/// Definition for PCI INTx pins.
+#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd)]
+pub enum IntXPin {
+    /// INTA
+    IntA = 0x1,
+    /// INTB
+    IntB = 0x2,
+    /// INTC
+    IntC = 0x3,
+    /// INTD
+    IntD = 0x4,
+}
+
+/// Standard configuration for Legacy interrupts.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct LegacyIrqConfig {
+    /// Input of the system interrupt controllers the device's interrupt pin is connected to.
+    /// Implemented by any device that makes use of an interrupt pin.
+    pub interrupt_line: Option<u32>,
+    /// Specifies which interrupt pin the device uses.
+    pub interrupt_pin: Option<IntXPin>,
+}
+
+/// Trait for defining properties of Legacy interrupts.
+pub trait LegacyInterrupt: ConfigurableInterrupt<Cfg = LegacyIrqConfig> {}
+
+/// Blanket implementation for Interrupts that use a LegacyIrqConfig.
+impl<T> LegacyInterrupt for T where T: ConfigurableInterrupt<Cfg = LegacyIrqConfig> {}

src/interrupt/mod.rs

@@ -0,0 +1,218 @@
+// Copyright (C) 2019-2020 Alibaba Cloud, Red Hat, Inc and Amazon.com, Inc. or its affiliates.
+// All Rights Reserved.
+
+// SPDX-License-Identifier: Apache-2.0 OR BSD-3-Clause
+
+//! Traits and Structs to manage interrupt sources for devices.
+//!
+//! In system programming, an interrupt is a signal to the processor emitted by hardware or
+//! software indicating an event that needs immediate attention. An interrupt alerts the processor
+//! to a high-priority condition requiring the interruption of the current code the processor is
+//! executing. The processor responds by suspending its current activities, saving its state, and
+//! executing a function called an interrupt handler (or an interrupt service routine, ISR) to deal
+//! with the event. This interruption is temporary, and, after the interrupt handler finishes,
+//! unless handling the interrupt has emitted a fatal error, the processor resumes normal
+//! activities.
+//!
+//! Hardware interrupts are used by devices to communicate that they require attention from the
+//! operating system, or a bare-metal program running on the CPU if there are no OSes. The act of
+//! initiating a hardware interrupt is referred to as an interrupt request (IRQ). Different devices
+//! are usually associated with different interrupts using a unique value associated with each
+//! interrupt. This makes it possible to know which hardware device caused which interrupts.
+//! These interrupt values are often called IRQ lines, or just interrupt lines.
+//!
+//! Nowadays, IRQ lines is not the only mechanism to deliver device interrupts to processors.
+//! MSI [(Message Signaled Interrupt)](https://en.wikipedia.org/wiki/Message_Signaled_Interrupts)
+//! is another commonly used alternative in-band method of signaling an interrupt, using special
+//! in-band messages to replace traditional out-of-band assertion of dedicated interrupt lines.
+//! While more complex to implement in a device, message signaled interrupts have some significant
+//! advantages over pin-based out-of-band interrupt signaling. Message signaled interrupts are
+//! supported in PCI bus since its version 2.2, and in later available PCI Express bus. Some non-PCI
+//! architectures also use message signaled interrupts.
+//!
+//! While IRQ is a term commonly used by Operating Systems when dealing with hardware
+//! interrupts, the IRQ numbers managed by OSes are independent of the ones managed by VMM.
+//! For simplicity sake, the term `Interrupt Source` is used instead of IRQ to represent both pin-based
+//! interrupts and MSI interrupts.
+//!
+//! A device may support multiple types of interrupts, and each type of interrupt may support one
+//! or multiple interrupt sources. For example, a PCI device may support:
+//! * Legacy Irq: exactly one interrupt source.
+//! * PCI MSI Irq: 1,2,4,8,16,32 interrupt sources.
+//! * PCI MSIx Irq: 2^n(n=0-11) interrupt sources.
+
+pub mod legacy;
+pub mod msi;
+
+use std::fmt::{self, Display};
+use std::ops::Deref;
+
+/// Errors associated with handling interrupts
+#[derive(Debug)]
+pub enum Error {
+    /// Operation not supported for this interrupt.
+    OperationNotSupported,
+
+    /// The specified configuration is not valid.
+    InvalidConfiguration,
+
+    /// The interrupt was not enabled.
+    InterruptNotChanged,
+
+    /// The interrupt could not be triggered.
+    InterruptNotTriggered,
+}
+
+impl std::error::Error for Error {}
+
+/// Reuse std::io::Result to simplify interoperability among crates.
+pub type Result<T> = std::result::Result<T, Error>;
+
+impl Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "Interrupt error: ")?;
+        match self {
+            Error::OperationNotSupported => write!(f, "operation not supported"),
+            Error::InvalidConfiguration => write!(f, "invalid configuration"),
+            Error::InterruptNotChanged => write!(f, "the interrupt state could not be changed"),
+            Error::InterruptNotTriggered => write!(f, "the interrupt could not be triggered"),
+        }
+    }
+}
+
+/// Trait used by interrupt producers to signal interrupts.
+///
+/// An object having the Interrupt Trait is shared between the VMM and the device
+/// that is using the interrupt.
+/// The `Interrupt` performs two main goals:
+///     * offers a control interface for the interrupt through the `enable()`
+///     and `disable()` methods;
+///     * offers a channel through which notifications can be passed between
+///     the VMM and the device;
+///
+/// When an `Interrupt` is triggered, a notification mechanism that is known by the
+/// Hypervisor will be used to signal the guest.
+///
+/// Objects implementing this trait are required to have internal mutability.
+pub trait Interrupt {
+    /// Inject an interrupt from this interrupt source into the guest.
+    fn trigger(&self) -> Result<()>;
+
+    /// EOI callback that will be called when the guest acknowledges the interrupt.
+    /// This can be used to resample and re-inject a level-triggered interrupt if the
+    /// device still requires service.
+    fn acknowledge(&self) -> Result<()> {
+        Err(Error::OperationNotSupported)
+    }
+
+    /// Enable generation of interrupts from this interrupt source.
+    fn enable(&self) -> Result<()> {
+        Err(Error::OperationNotSupported)
+    }
+
+    /// Disable generation of interrupts from this interrupt source.
+    fn disable(&self) -> Result<()> {
+        Err(Error::OperationNotSupported)
+    }
+}
+
+/// Trait that provides access to the underlying notification objects used by the
+/// hypervisor.
+///
+/// The type of the underlying notification mechanism used by the `Interrupt` is
+/// defined by the `NotifierType` associated type.
+/// `InterruptWithNotifiers` allows access to the undelying mechanism used by the
+/// Hypervisor through the `trigger_notifier()` and `ack_notifier()` methods.
+/// This enables some use cases where the device may want to bypass the VMM completely
+/// or when the device crate acts only as a control plane and the actual emulation is
+/// implemented in some other component that understands the underlying mechanism.
+///
+/// A notable example is VFIO that allows a device to register the irqfd so that
+/// interrupts follow a fast path that doesn't require going through the VMM.
+/// VFIO supports the registration of a `resamplefd` which would be returned by
+/// `ack_notifier`.
+///
+/// Implementations of this trait must provide the trigger notifier object.
+pub trait InterruptWithNotifiers: Interrupt {
+    /// The type of the underlying mechanism used for notifications by this interrupt.
+    type NotifierType;
+
+    /// Returns an interrupt notifier from this interrupt.
+    ///
+    /// An interrupt notifier allows for external components and processes
+    /// to inject interrupts into a guest through a different interface other
+    /// than `trigger()`.
+    fn trigger_notifier(&self) -> &Self::NotifierType;
+
+    /// Returns an end-of-interrupt notifier from this interrupt.
+    ///
+    /// An end-of-interrupt notifier allows for external components and processes
+    /// to be notified when a guest acknowledges an interrupt. This can be used
+    /// to resample and inject a level-triggered interrupt, or to mitigate the
+    /// effect of lost timer interrupts.
+    fn ack_notifier(&self) -> Option<&Self::NotifierType> {
+        None
+    }
+}
+
+/// Trait for interrupts that allow users to configure interrupt parameters.
+///
+/// This enhances the control plane interface of the `Interrupt` by allowing
+/// a device to configure the behavior of the interrupt.
+pub trait ConfigurableInterrupt: Interrupt {
+    /// Type describing the configuration spec of the interrupt.
+    type Cfg;
+
+    /// Update configuration of the interrupt.
+    fn update(&self, config: &Self::Cfg) -> Result<()>;
+
+    /// Returns the current configuration of the interrupt.
+    fn get_config(&self) -> Result<Self::Cfg>;
+}
+
+/// Trait for interrupts that can be masked or unmasked.
+pub trait MaskableInterrupt: Interrupt {
+    /// Mask the interrupt.  Masked interrupts are remembered but
+    /// not delivered.
+    fn mask(&self) -> Result<()>;
+
+    /// Unmask the interrupt, delivering it if it was pending.
+    fn unmask(&self) -> Result<()>;
+}
+
+/// Trait to manage a group of interrupt sources for a device.
+///
+/// A device may use an InterruptSourceGroup to manage multiple interrupts of the same type.
+/// The group allows a device to request and release interrupts and perform actions on the
+/// whole collection of interrupts like enable and disable for cases where enabling or disabling
+/// a single interrupt in the group does not make sense. For example, PCI MSI interrupts must be
+/// enabled as a group.
+pub trait InterruptSourceGroup: Send {
+    /// Type of the interrupts contained in this group.
+    type InterruptType: Interrupt;
+
+    /// Interrupt Type returned by get
+    type InterruptWrapper: Deref<Target = Self::InterruptType>;
+
+    /// Return whether the group manages no interrupts.
+    fn is_empty(&self) -> bool;
+
+    /// Get number of interrupt sources managed by the group.
+    fn len(&self) -> usize;
+
+    /// Enable the interrupt sources in the group to generate interrupts.
+    fn enable(&self) -> Result<()>;
+
+    /// Disable the interrupt sources in the group to generate interrupts.
+    fn disable(&self) -> Result<()>;
+
+    /// Return the index-th interrupt in the group, or `None` if the index is out
+    /// of bounds.
+    fn get(&self, index: usize) -> Option<Self::InterruptWrapper>;
+
+    /// Request new interrupts within this group.
+    fn allocate_interrupts(&mut self, size: usize) -> Result<()>;
+
+    /// Release all interrupts within this group.
+    fn free_interrupts(&mut self) -> Result<()>;
+}

src/interrupt/msi.rs

@@ -0,0 +1,32 @@
+// Copyright (C) 2021 Amazon.com, Inc. or its affiliates.
+// All Rights Reserved.
+
+// SPDX-License-Identifier: Apache-2.0 OR BSD-3-Clause
+
+//! Traits and Structs to manage MSI interrupt sources for devices.
+//!
+//! MSI interrupts are typically used by PCI devices.
+//! These structs and traits can be used to configure both MSI and MSIX interrupts.
+
+use crate::interrupt::{ConfigurableInterrupt, MaskableInterrupt};
+
+/// Configuration data for MSI/MSI-X interrupts.
+///
+/// On x86 platforms, these interrupts are vectors delivered directly to the LAPIC.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct MsiIrqConfig {
+    /// High address to delivery message signaled interrupt.
+    pub high_addr: u32,
+    /// Low address to delivery message signaled interrupt.
+    pub low_addr: u32,
+    /// Data to write to delivery message signaled interrupt.
+    pub data: u32,
+    /// Unique ID of the device to delivery message signaled interrupt.
+    pub devid: u32,
+}
+
+/// Trait for defining properties of MSI interrupts.
+pub trait MsiInterrupt: ConfigurableInterrupt<Cfg = MsiIrqConfig> + MaskableInterrupt {}
+
+/// Blanket implementation for Interrupts that use a MsiIrqConfig.
+impl<T> MsiInterrupt for T where T: ConfigurableInterrupt<Cfg = MsiIrqConfig> + MaskableInterrupt {}

src/lib.rs

@@ -52,6 +52,7 @@
 
 pub mod bus;
 pub mod device_manager;
+pub mod interrupt;
 pub mod resources;
 
 use std::ops::Deref;