acpi: add ACPI support in Firecracker

Initial ACPI setup for x86.

We have FADT in Hardware Reduced mode. This means that we declare to the
guest that we don't implement in "hardware" some features, such as
control and event registers.

We also have MADT, which essentially replaces the functionality of
MPTable; we define on IO-APIC and one LocalAPIC structure per vCPU. All
vCPUs are marked as online by default.

Finally, we have an empty DSDT. This will be populated with info about
VirtIO, legacy and ACPI devices in future commits.

Signed-off-by: Babis Chalios <[email protected]>

Author: bchalios

Cargo.lock

@@ -38,10 +38,12 @@ micro_http = { git = "https://github.com/firecracker-microvm/micro-http" }
 log-instrument = { path = "../log-instrument", optional = true }
 crc64 = "2.0.0"
 slab = "0.4.7"
+zerocopy = { version = "0.7.32" }
 
 seccompiler = { path = "../seccompiler" }
 utils = { path = "../utils" }
 smallvec = "1.11.2"
+acpi_tables = { path = "../acpi-tables" } 
 
 [target.'cfg(target_arch = "aarch64")'.dependencies]
 vm-fdt = "0.2.0"

src/vmm/Cargo.toml

@@ -0,0 +1,277 @@
+// Copyright 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+use acpi_tables::fadt::{FADT_F_HW_REDUCED_ACPI, FADT_F_PWR_BUTTON, FADT_F_SLP_BUTTON};
+use acpi_tables::{Dsdt, Fadt, Madt, Rsdp, Sdt, Xsdt};
+use log::{debug, error};
+use vm_allocator::AllocPolicy;
+
+use crate::acpi::x86_64::{
+    apic_addr, rsdp_addr, setup_arch_dsdt, setup_arch_fadt, setup_interrupt_controllers,
+};
+use crate::device_manager::resources::ResourceAllocator;
+use crate::vstate::memory::{GuestAddress, GuestMemoryMmap};
+use crate::Vcpu;
+
+mod x86_64;
+
+// Our (Original Equipment Manufacturer" (OEM) name. OEM is how ACPI names the manufacturer of the
+// hardware that is exposed to the OS, through ACPI tables. The OEM name is passed in every ACPI
+// table, to let the OS know that we are the owner of the table.
+const OEM_ID: [u8; 6] = *b"FIRECK";
+
+// In reality the OEM revision is per table and it defines the revision of the OEM's implementation
+// of the particular ACPI table. For our purpose, we can set it to a fixed value for all the tables
+const OEM_REVISION: u32 = 0;
+
+// This is needed for an entry in the FADT table. Populating this entry in FADT is a way to let the
+// guest know that it runs within a Firecracker microVM.
+const HYPERVISOR_VENDOR_ID: [u8; 8] = *b"FIRECKVM";
+
+#[derive(Debug, thiserror::Error, displaydoc::Display)]
+/// Error type for ACPI related operations
+pub enum AcpiError {
+    /// Could not allocate resources: {0}
+    VmAllocator(#[from] vm_allocator::Error),
+    /// ACPI tables error: {0}
+    AcpiTables(#[from] acpi_tables::AcpiError),
+}
+
+/// Helper type that holds the guest memory in which we write the tables in and a resource
+/// allocator for allocating space for the tables
+struct AcpiTableWriter<'a> {
+    mem: &'a GuestMemoryMmap,
+    resource_allocator: &'a mut ResourceAllocator,
+}
+
+impl<'a> AcpiTableWriter<'a> {
+    /// Write a table in guest memory
+    ///
+    /// This will allocate enough space inside guest memory and write the table in the allocated
+    /// buffer. It returns the address in which it wrote the table.
+    fn write_acpi_table<S>(&mut self, table: &mut S) -> Result<u64, AcpiError>
+    where
+        S: Sdt,
+    {
+        let addr = self.resource_allocator.allocate_system_memory(
+            table.len().try_into().unwrap(),
+            1,
+            AllocPolicy::FirstMatch,
+        )?;
+
+        table
+            .write_to_guest(self.mem, GuestAddress(addr))
+            .inspect_err(|err| error!("acpi: Could not write table in guest memory: {err}"))?;
+
+        debug!(
+            "acpi: Wrote table ({} bytes) at address: {:#010x}",
+            table.len(),
+            addr
+        );
+
+        Ok(addr)
+    }
+
+    /// Build the DSDT table for the guest
+    fn build_dsdt(&mut self) -> Result<u64, AcpiError> {
+        let mut dsdt_data = Vec::new();
+
+        // Architecture specific DSDT data
+        setup_arch_dsdt(&mut dsdt_data);
+
+        let mut dsdt = Dsdt::new(OEM_ID, *b"FCVMDSDT", OEM_REVISION, dsdt_data);
+        self.write_acpi_table(&mut dsdt)
+    }
+
+    /// Build the FADT table for the guest
+    ///
+    /// This includes a pointer with the location of the DSDT in guest memory
+    fn build_fadt(&mut self, dsdt_addr: u64) -> Result<u64, AcpiError> {
+        let mut fadt = Fadt::new(OEM_ID, *b"FCVMFADT", OEM_REVISION);
+        fadt.set_hypervisor_vendor_id(HYPERVISOR_VENDOR_ID);
+        fadt.set_x_dsdt(dsdt_addr);
+        fadt.set_flags(
+            1 << FADT_F_HW_REDUCED_ACPI | 1 << FADT_F_PWR_BUTTON | 1 << FADT_F_SLP_BUTTON,
+        );
+        setup_arch_fadt(&mut fadt);
+        self.write_acpi_table(&mut fadt)
+    }
+
+    /// Build the MADT table for the guest
+    ///
+    /// This includes information about the interrupt controllers supported in the platform
+    fn build_madt(&mut self, nr_vcpus: u8) -> Result<u64, AcpiError> {
+        let mut madt = Madt::new(
+            OEM_ID,
+            *b"FCVMMADT",
+            OEM_REVISION,
+            apic_addr(),
+            setup_interrupt_controllers(nr_vcpus),
+        );
+        self.write_acpi_table(&mut madt)
+    }
+
+    /// Build the XSDT table for the guest
+    ///
+    /// Currently, we pass to the guest just FADT and MADT tables.
+    fn build_xsdt(&mut self, fadt_addr: u64, madt_addr: u64) -> Result<u64, AcpiError> {
+        let mut xsdt = Xsdt::new(
+            OEM_ID,
+            *b"FCMVXSDT",
+            OEM_REVISION,
+            vec![fadt_addr, madt_addr],
+        );
+        self.write_acpi_table(&mut xsdt)
+    }
+
+    /// Build the RSDP pointer for the guest.
+    ///
+    /// This will build the RSDP pointer which points to the XSDT table and write it in guest
+    /// memory. The address in which we write RSDP is pre-determined for every architecture.
+    /// We will not allocate arbitrary memory for it
+    fn build_rsdp(&mut self, xsdt_addr: u64) -> Result<(), AcpiError> {
+        let mut rsdp = Rsdp::new(OEM_ID, xsdt_addr);
+        rsdp.write_to_guest(self.mem, rsdp_addr())
+            .inspect_err(|err| error!("acpi: Could not write RSDP in guest memory: {err}"))?;
+
+        debug!(
+            "acpi: Wrote RSDP ({} bytes) at address: {:#010x}",
+            rsdp.len(),
+            rsdp_addr().0
+        );
+        Ok(())
+    }
+}
+
+/// Create ACPI tables for the guest
+///
+/// This will create the ACPI tables needed to describe to the guest OS the available hardware,
+/// such as interrupt controllers, vCPUs and VirtIO devices.
+pub(crate) fn create_acpi_tables(
+    mem: &GuestMemoryMmap,
+    resource_allocator: &mut ResourceAllocator,
+    vcpus: &[Vcpu],
+) -> Result<(), AcpiError> {
+    let mut writer = AcpiTableWriter {
+        mem,
+        resource_allocator,
+    };
+
+    let dsdt_addr = writer.build_dsdt()?;
+    let fadt_addr = writer.build_fadt(dsdt_addr)?;
+    let madt_addr = writer.build_madt(vcpus.len().try_into().unwrap())?;
+    let xsdt_addr = writer.build_xsdt(fadt_addr, madt_addr)?;
+    writer.build_rsdp(xsdt_addr)
+}
+
+#[cfg(test)]
+pub mod tests {
+    use acpi_tables::Sdt;
+    use vm_memory::Bytes;
+
+    use crate::acpi::{AcpiError, AcpiTableWriter};
+    use crate::arch::x86_64::layout::{SYSTEM_MEM_SIZE, SYSTEM_MEM_START};
+    use crate::builder::tests::default_vmm;
+    use crate::utilities::test_utils::arch_mem;
+
+    struct MockSdt(Vec<u8>);
+
+    impl Sdt for MockSdt {
+        fn len(&self) -> usize {
+            self.0.len()
+        }
+
+        fn write_to_guest<M: vm_memory::GuestMemory>(
+            &mut self,
+            mem: &M,
+            address: vm_memory::GuestAddress,
+        ) -> acpi_tables::Result<()> {
+            mem.write_slice(&self.0, address)?;
+            Ok(())
+        }
+    }
+
+    // Currently we are allocating up to SYSTEM_MEM_SIZE memory for ACPI tables. We are allocating
+    // using the FirstMatch policy, with an 1 byte alignment. This test checks that we are able to
+    // allocate up to this size, and get back the expected addresses.
+    #[test]
+    fn test_write_acpi_table_memory_allocation() {
+        // A mocke Vmm object with 128MBs of memory
+        let mut vmm = default_vmm();
+        let mut writer = AcpiTableWriter {
+            mem: &vmm.guest_memory,
+            resource_allocator: &mut vmm.resource_allocator,
+        };
+
+        // This should succeed
+        let mut sdt = MockSdt(vec![0; 4096]);
+        let addr = writer.write_acpi_table(&mut sdt).unwrap();
+        assert_eq!(addr, SYSTEM_MEM_START);
+
+        // Let's try to write two 4K pages plus one byte
+        let mut sdt = MockSdt(vec![0; usize::try_from(SYSTEM_MEM_SIZE + 1).unwrap()]);
+        let err = writer.write_acpi_table(&mut sdt).unwrap_err();
+        assert!(
+            matches!(
+                err,
+                AcpiError::VmAllocator(vm_allocator::Error::ResourceNotAvailable)
+            ),
+            "{:?}",
+            err
+        );
+
+        // We are allocating memory for tables with alignment of 1 byte. All of these should
+        // succeed.
+        let mut sdt = MockSdt(vec![0; 5]);
+        let addr = writer.write_acpi_table(&mut sdt).unwrap();
+        assert_eq!(addr, SYSTEM_MEM_START + 4096);
+        let mut sdt = MockSdt(vec![0; 2]);
+        let addr = writer.write_acpi_table(&mut sdt).unwrap();
+        assert_eq!(addr, SYSTEM_MEM_START + 4101);
+        let mut sdt = MockSdt(vec![0; 4]);
+        let addr = writer.write_acpi_table(&mut sdt).unwrap();
+        assert_eq!(addr, SYSTEM_MEM_START + 4103);
+        let mut sdt = MockSdt(vec![0; 8]);
+        let addr = writer.write_acpi_table(&mut sdt).unwrap();
+        assert_eq!(addr, SYSTEM_MEM_START + 4107);
+        let mut sdt = MockSdt(vec![0; 16]);
+        let addr = writer.write_acpi_table(&mut sdt).unwrap();
+        assert_eq!(addr, SYSTEM_MEM_START + 4115);
+    }
+
+    // If, for whatever weird reason, we end up with microVM that has less memory than the maximum
+    // address we allocate for ACPI tables, we would be able to allocate the tables but we would
+    // not be able to write them. This is practically impossible in our case. If we get such a
+    // guest memory, we won't be able to load the guest kernel, but the function does
+    // return an error on this case, so let's just check that in case any of these assumptions
+    // change in the future.
+    #[test]
+    fn test_write_acpi_table_small_memory() {
+        let mut vmm = default_vmm();
+        vmm.guest_memory = arch_mem(
+            (SYSTEM_MEM_START + SYSTEM_MEM_SIZE - 4096)
+                .try_into()
+                .unwrap(),
+        );
+        let mut writer = AcpiTableWriter {
+            mem: &vmm.guest_memory,
+            resource_allocator: &mut vmm.resource_allocator,
+        };
+
+        let mut sdt = MockSdt(vec![0; usize::try_from(SYSTEM_MEM_SIZE).unwrap()]);
+        let err = writer.write_acpi_table(&mut sdt).unwrap_err();
+        assert!(
+            matches!(
+                err,
+                AcpiError::AcpiTables(acpi_tables::AcpiError::GuestMemory(
+                    vm_memory::GuestMemoryError::PartialBuffer {
+                        expected: 263168,  // SYSTEM_MEM_SIZE
+                        completed: 259072  // SYSTEM_MEM_SIZE - 4096
+                    },
+                ))
+            ),
+            "{:?}",
+            err
+        );
+    }
+}

src/vmm/src/acpi/mod.rs

@@ -0,0 +1,52 @@
+// Copyright 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+use std::mem::size_of;
+
+use acpi_tables::fadt::{
+    IAPC_BOOT_ARG_FLAGS_MSI_NOT_PRESENT, IAPC_BOOT_ARG_FLAGS_PCI_ASPM,
+    IAPC_BOOT_ARG_FLAGS_VGA_NOT_PRESENT,
+};
+use acpi_tables::madt::{IoAPIC, LocalAPIC};
+use acpi_tables::Fadt;
+use vm_memory::GuestAddress;
+use zerocopy::AsBytes;
+
+use crate::arch::x86_64::layout;
+
+#[inline(always)]
+pub(crate) fn setup_interrupt_controllers(nr_vcpus: u8) -> Vec<u8> {
+    let mut ic =
+        Vec::with_capacity(size_of::<IoAPIC>() + (nr_vcpus as usize) * size_of::<LocalAPIC>());
+
+    ic.extend_from_slice(IoAPIC::new(0, layout::IOAPIC_ADDR).as_bytes());
+    for i in 0..nr_vcpus {
+        ic.extend_from_slice(LocalAPIC::new(i).as_bytes());
+    }
+    ic
+}
+
+#[inline(always)]
+pub(crate) fn setup_arch_fadt(fadt: &mut Fadt) {
+    // Let the guest kernel know that there is not VGA hardware present
+    // neither do we support ASPM, or MSI type of interrupts.
+    // More info here:
+    // https://uefi.org/specs/ACPI/6.5/05_ACPI_Software_Programming_Model.html?highlight=0a06#ia-pc-boot-architecture-flags
+    fadt.setup_iapc_flags(
+        1 << IAPC_BOOT_ARG_FLAGS_VGA_NOT_PRESENT
+            | 1 << IAPC_BOOT_ARG_FLAGS_PCI_ASPM
+            | 1 << IAPC_BOOT_ARG_FLAGS_MSI_NOT_PRESENT,
+    );
+}
+
+#[allow(clippy::ptr_arg)]
+#[inline(always)]
+pub(crate) fn setup_arch_dsdt(_dsdt_data: &mut Vec<u8>) {}
+
+pub(crate) const fn apic_addr() -> u32 {
+    layout::APIC_ADDR
+}
+
+pub(crate) const fn rsdp_addr() -> GuestAddress {
+    GuestAddress(layout::RSDP_ADDR)
+}

src/vmm/src/acpi/x86_64.rs

@@ -22,8 +22,9 @@ pub mod x86_64;
 
 #[cfg(target_arch = "x86_64")]
 pub use crate::arch::x86_64::{
-    arch_memory_regions, configure_system, get_kernel_start, initrd_load_addr,
-    layout::CMDLINE_MAX_SIZE, layout::IRQ_BASE, layout::IRQ_MAX, ConfigurationError, MMIO_MEM_SIZE,
+    arch_memory_regions, configure_system, get_kernel_start, initrd_load_addr, layout::APIC_ADDR,
+    layout::CMDLINE_MAX_SIZE, layout::IOAPIC_ADDR, layout::IRQ_BASE, layout::IRQ_MAX,
+    layout::SYSTEM_MEM_SIZE, layout::SYSTEM_MEM_START, ConfigurationError, MMIO_MEM_SIZE,
     MMIO_MEM_START,
 };