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)]
+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)]
+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>,
+}
+
+/// Supertrait 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

@@ -1,9 +1,52 @@
-// Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// 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::result::Result;
+use std::fmt::{self, Display};
+use std::io;
+use std::ops::Deref;
 
 /// Abstraction for a simple, push-button like interrupt mechanism.
 /// This helps in abstracting away how events/interrupts are generated when
@@ -18,5 +61,140 @@ pub trait Trigger {
     type E: std::fmt::Debug;
 
     /// Trigger an event.
-    fn trigger(&self) -> Result<(), Self::E>;
+    fn trigger(&self) -> std::result::Result<(), Self::E>;
+}
+
+/// 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.
+    InterruptNotEnabled,
+
+    /// Generic IO error,
+    IOError(io::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::InterruptNotEnabled => write!(f, "the interrupt was not enabled"),
+            Error::IOError(error) => write!(f, "{}", error),
+        }
+    }
+}
+
+impl From<io::Error> for Error {
+    fn from(e: io::Error) -> Error {
+        Error::IOError(e)
+    }
+}
+
+/// Trait for interrupt producers.
+pub trait Interrupt {
+    /// The type of Trigger object used for notifications by this interrupt.
+    type TriggerType: Trigger;
+
+    /// Inject an interrupt from this interrupt source into the guest.
+    fn trigger(&self) -> std::result::Result<(), <Self::TriggerType as Trigger>::E>;
+
+    /// Returns an interrupt notifier from this interrupt.
+    ///
+    /// An interrupt notifier allows for external components and processes
+    /// to inject interrupts into a guest, by writing to the file returned
+    /// by this method.
+    fn notifier(&self) -> Option<Self::TriggerType> {
+        None
+    }
+
+    /// Called back when the CPU acknowledges the interrupt.
+    fn acknowledge(&self) {}
+
+    /// 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::TriggerType> {
+        None
+    }
+
+    /// Enable generation of interrupts from this interrupt source.
+    fn enable(&self) -> Result<()>;
+
+    /// Disable generation of interrupts from this interrupt source.
+    fn disable(&self) -> Result<()> {
+        Err(Error::OperationNotSupported)
+    }
+}
+
+/// Trait for interrupts that allow users to configure interrupt parameters.
+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)]
+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,
+}
+
+/// Supertrait 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 {}