Move contents of `rsdp` into `acpi`

Now `acpi` can be used from an allocator-less environment, the original
motivation of the `rsdp` crate has been removed. We can therefore move
towards deprecating it, and maintaining one less crate!

acpi/Cargo.toml

@@ -12,7 +12,6 @@ edition = "2021"
 [dependencies]
 bit_field = "0.10.2"
 log = "0.4.20"
-rsdp = { version = "2", path = "../rsdp" }
 
 [features]
 default = ["allocator_api", "alloc"]

acpi/src/handler.rs

@@ -0,0 +1,128 @@
+use core::{ops::Deref, ptr::NonNull};
+
+/// Describes a physical mapping created by `AcpiHandler::map_physical_region` and unmapped by
+/// `AcpiHandler::unmap_physical_region`. The region mapped must be at least `size_of::<T>()`
+/// bytes, but may be bigger.
+///
+/// See `PhysicalMapping::new` for the meaning of each field.
+#[derive(Debug)]
+pub struct PhysicalMapping<H, T>
+where
+    H: AcpiHandler,
+{
+    physical_start: usize,
+    virtual_start: NonNull<T>,
+    region_length: usize, // Can be equal or larger than size_of::<T>()
+    mapped_length: usize, // Differs from `region_length` if padding is added for alignment
+    handler: H,
+}
+
+impl<H, T> PhysicalMapping<H, T>
+where
+    H: AcpiHandler,
+{
+    /// Construct a new `PhysicalMapping`.
+    ///
+    /// - `physical_start` should be the physical address of the structure to be mapped.
+    /// - `virtual_start` should be the corresponding virtual address of that structure. It may differ from the
+    ///   start of the region mapped due to requirements of the paging system. It must be a valid, non-null
+    ///   pointer.
+    /// - `region_length` should be the number of bytes requested to be mapped. It must be equal to or larger than
+    ///   `size_of::<T>()`.
+    /// - `mapped_length` should be the number of bytes mapped to fulfill the request. It may be equal to or larger
+    ///   than `region_length`, due to requirements of the paging system or other reasoning.
+    /// - `handler` should be the same `AcpiHandler` that created the mapping. When the `PhysicalMapping` is
+    ///   dropped, it will be used to unmap the structure.
+    pub unsafe fn new(
+        physical_start: usize,
+        virtual_start: NonNull<T>,
+        region_length: usize,
+        mapped_length: usize,
+        handler: H,
+    ) -> Self {
+        Self { physical_start, virtual_start, region_length, mapped_length, handler }
+    }
+
+    pub fn physical_start(&self) -> usize {
+        self.physical_start
+    }
+
+    pub fn virtual_start(&self) -> NonNull<T> {
+        self.virtual_start
+    }
+
+    pub fn region_length(&self) -> usize {
+        self.region_length
+    }
+
+    pub fn mapped_length(&self) -> usize {
+        self.mapped_length
+    }
+
+    pub fn handler(&self) -> &H {
+        &self.handler
+    }
+}
+
+unsafe impl<H: AcpiHandler + Send, T: Send> Send for PhysicalMapping<H, T> {}
+
+impl<H, T> Deref for PhysicalMapping<H, T>
+where
+    H: AcpiHandler,
+{
+    type Target = T;
+
+    fn deref(&self) -> &T {
+        unsafe { self.virtual_start.as_ref() }
+    }
+}
+
+impl<H, T> Drop for PhysicalMapping<H, T>
+where
+    H: AcpiHandler,
+{
+    fn drop(&mut self) {
+        H::unmap_physical_region(self)
+    }
+}
+
+/// An implementation of this trait must be provided to allow `acpi` to access platform-specific
+/// functionality, such as mapping regions of physical memory. You are free to implement these
+/// however you please, as long as they conform to the documentation of each function. The handler is stored in
+/// every `PhysicalMapping` so it's able to unmap itself when dropped, so this type needs to be something you can
+/// clone/move about freely (e.g. a reference, wrapper over `Rc`, marker struct, etc.).
+pub trait AcpiHandler: Clone {
+    /// Given a physical address and a size, map a region of physical memory that contains `T` (note: the passed
+    /// size may be larger than `size_of::<T>()`). The address is not neccessarily page-aligned, so the
+    /// implementation may need to map more than `size` bytes. The virtual address the region is mapped to does not
+    /// matter, as long as it is accessible to `acpi`.
+    ///
+    /// See the documentation on `PhysicalMapping::new` for an explanation of each field on the `PhysicalMapping`
+    /// return type.
+    ///
+    /// ## Safety
+    ///
+    /// - `physical_address` must point to a valid `T` in physical memory.
+    /// - `size` must be at least `size_of::<T>()`.
+    unsafe fn map_physical_region<T>(&self, physical_address: usize, size: usize) -> PhysicalMapping<Self, T>;
+
+    /// Unmap the given physical mapping. This is called when a `PhysicalMapping` is dropped, you should **not** manually call this.
+    ///
+    /// Note: A reference to the handler used to construct `region` can be acquired by calling [`PhysicalMapping::handler`].
+    fn unmap_physical_region<T>(region: &PhysicalMapping<Self, T>);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    #[allow(dead_code)]
+    fn test_send_sync() {
+        // verify that PhysicalMapping implements Send and Sync
+        fn test_send_sync<T: Send>() {}
+        fn caller<H: AcpiHandler + Send, T: Send>() {
+            test_send_sync::<PhysicalMapping<H, T>>();
+        }
+    }
+}

acpi/src/lib.rs

@@ -69,9 +69,11 @@ extern crate alloc;
 pub mod address;
 pub mod bgrt;
 pub mod fadt;
+pub mod handler;
 pub mod hpet;
 pub mod madt;
 pub mod mcfg;
+pub mod rsdp;
 pub mod sdt;
 
 #[cfg(feature = "allocator_api")]
@@ -88,12 +90,9 @@ pub use crate::platform::{interrupt::InterruptModel, PlatformInfo};
 pub use crate::mcfg::PciConfigRegions;
 
 pub use fadt::PowerProfile;
+pub use handler::{AcpiHandler, PhysicalMapping};
 pub use hpet::HpetInfo;
 pub use madt::MadtError;
-pub use rsdp::{
-    handler::{AcpiHandler, PhysicalMapping},
-    RsdpError,
-};
 
 use crate::sdt::{SdtHeader, Signature};
 use core::mem;
@@ -126,7 +125,10 @@ pub unsafe trait AcpiTable {
 /// Error type used by functions that return an `AcpiResult<T>`.
 #[derive(Debug)]
 pub enum AcpiError {
-    Rsdp(RsdpError),
+    NoValidRsdp,
+    RsdpIncorrectSignature,
+    RsdpInvalidOemId,
+    RsdpInvalidChecksum,
 
     SdtInvalidSignature(Signature),
     SdtInvalidOemId(Signature),
@@ -147,8 +149,8 @@ pub enum AcpiError {
 ///
 /// ### Implementation Note
 ///
-/// When using the `allocator_api` feature, [`PlatformInfo::new()`] provides a much cleaner
-/// API for enumerating ACPI structures once an `AcpiTables` has been constructed.
+/// When using the `allocator_api`±`alloc` features, [`PlatformInfo::new()`] or [`PlatformInfo::new_in()`] provide
+/// a much cleaner API for enumerating ACPI structures once an `AcpiTables` has been constructed.
 #[derive(Debug)]
 pub struct AcpiTables<H: AcpiHandler> {
     mapping: PhysicalMapping<H, SdtHeader>,
@@ -165,9 +167,9 @@ where
     /// ### Safety: Caller must ensure the provided address is valid to read as an RSDP.
     pub unsafe fn from_rsdp(handler: H, address: usize) -> AcpiResult<Self> {
         let rsdp_mapping = unsafe { handler.map_physical_region::<Rsdp>(address, mem::size_of::<Rsdp>()) };
-        rsdp_mapping.validate().map_err(AcpiError::Rsdp)?;
+        rsdp_mapping.validate()?;
 
-        // Safety: `RSDP` has been validated.
+        // Safety: RSDP has been validated.
         unsafe { Self::from_validated_rsdp(handler, rsdp_mapping) }
     }
 
@@ -175,7 +177,7 @@ where
     /// work on UEFI platforms. See [Rsdp::search_for_rsdp_bios](rsdp_search::Rsdp::search_for_rsdp_bios) for
     /// details.
     pub unsafe fn search_for_rsdp_bios(handler: H) -> AcpiResult<Self> {
-        let rsdp_mapping = unsafe { Rsdp::search_for_on_bios(handler.clone()) }.map_err(AcpiError::Rsdp)?;
+        let rsdp_mapping = unsafe { Rsdp::search_for_on_bios(handler.clone())? };
         // Safety: RSDP has been validated from `Rsdp::search_for_on_bios`
         unsafe { Self::from_validated_rsdp(handler, rsdp_mapping) }
     }
@@ -206,7 +208,7 @@ where
                 drop(rsdp_mapping);
 
                 // Map and validate root table
-                // SAFETY: Addresses from a validated `RSDP` are also guaranteed to be valid.
+                // SAFETY: Addresses from a validated RSDP are also guaranteed to be valid.
                 let table_mapping = unsafe { read_table::<_, RootTable>(handler.clone(), table_phys_start) }?;
 
                 // Convert `table_mapping` to header mapping for storage

acpi/src/rsdp.rs

@@ -0,0 +1,214 @@
+use crate::{AcpiError, AcpiHandler, AcpiResult, PhysicalMapping};
+use core::{mem, ops::Range, slice, str};
+
+/// The size in bytes of the ACPI 1.0 RSDP.
+const RSDP_V1_LENGTH: usize = 20;
+/// The total size in bytes of the RSDP fields introduced in ACPI 2.0.
+const RSDP_V2_EXT_LENGTH: usize = mem::size_of::<Rsdp>() - RSDP_V1_LENGTH;
+
+/// The first structure found in ACPI. It just tells us where the RSDT is.
+///
+/// On BIOS systems, it is either found in the first 1KiB of the Extended Bios Data Area, or between `0x000e0000`
+/// and `0x000fffff`. The signature is always on a 16 byte boundary. On (U)EFI, it may not be located in these
+/// locations, and so an address should be found in the EFI configuration table instead.
+///
+/// The recommended way of locating the RSDP is to let the bootloader do it - Multiboot2 can pass a
+/// tag with the physical address of it. If this is not possible, a manual scan can be done.
+///
+/// If `revision > 0`, (the hardware ACPI version is Version 2.0 or greater), the RSDP contains
+/// some new fields. For ACPI Version 1.0, these fields are not valid and should not be accessed.
+/// For ACPI Version 2.0+, `xsdt_address` should be used (truncated to `u32` on x86) instead of
+/// `rsdt_address`.
+#[derive(Clone, Copy, Debug)]
+#[repr(C, packed)]
+pub struct Rsdp {
+    signature: [u8; 8],
+    checksum: u8,
+    oem_id: [u8; 6],
+    revision: u8,
+    rsdt_address: u32,
+
+    /*
+     * These fields are only valid for ACPI Version 2.0 and greater
+     */
+    length: u32,
+    xsdt_address: u64,
+    ext_checksum: u8,
+    reserved: [u8; 3],
+}
+
+impl Rsdp {
+    /// This searches for a RSDP on BIOS systems.
+    ///
+    /// ### Safety
+    /// This function probes memory in three locations:
+    ///    - It reads a word from `40:0e` to locate the EBDA.
+    ///    - The first 1KiB of the EBDA (Extended BIOS Data Area).
+    ///    - The BIOS memory area at `0xe0000..=0xfffff`.
+    ///
+    /// This should be fine on all BIOS systems. However, UEFI platforms are free to put the RSDP wherever they
+    /// please, so this won't always find the RSDP. Further, prodding these memory locations may have unintended
+    /// side-effects. On UEFI systems, the RSDP should be found in the Configuration Table, using two GUIDs:
+    ///     - ACPI v1.0 structures use `eb9d2d30-2d88-11d3-9a16-0090273fc14d`.
+    ///     - ACPI v2.0 or later structures use `8868e871-e4f1-11d3-bc22-0080c73c8881`.
+    /// You should search the entire table for the v2.0 GUID before searching for the v1.0 one.
+    pub unsafe fn search_for_on_bios<H>(handler: H) -> AcpiResult<PhysicalMapping<H, Rsdp>>
+    where
+        H: AcpiHandler,
+    {
+        let rsdp_address = find_search_areas(handler.clone()).iter().find_map(|area| {
+            // Map the search area for the RSDP followed by `RSDP_V2_EXT_LENGTH` bytes so an ACPI 1.0 RSDP at the
+            // end of the area can be read as an `Rsdp` (which always has the size of an ACPI 2.0 RSDP)
+            let mapping = unsafe {
+                handler.map_physical_region::<u8>(area.start, area.end - area.start + RSDP_V2_EXT_LENGTH)
+            };
+
+            let extended_area_bytes =
+                unsafe { slice::from_raw_parts(mapping.virtual_start().as_ptr(), mapping.region_length()) };
+
+            // Search `Rsdp`-sized windows at 16-byte boundaries relative to the base of the area (which is also
+            // aligned to 16 bytes due to the implementation of `find_search_areas`)
+            extended_area_bytes.windows(mem::size_of::<Rsdp>()).step_by(16).find_map(|maybe_rsdp_bytes_slice| {
+                let maybe_rsdp_virt_ptr = maybe_rsdp_bytes_slice.as_ptr().cast::<Rsdp>();
+                let maybe_rsdp_phys_start = maybe_rsdp_virt_ptr as usize
+                    - mapping.virtual_start().as_ptr() as usize
+                    + mapping.physical_start();
+                // SAFETY: `maybe_rsdp_virt_ptr` points to an aligned, readable `Rsdp`-sized value, and the `Rsdp`
+                // struct's fields are always initialized.
+                let maybe_rsdp = unsafe { &*maybe_rsdp_virt_ptr };
+
+                match maybe_rsdp.validate() {
+                    Ok(()) => Some(maybe_rsdp_phys_start),
+                    Err(AcpiError::RsdpIncorrectSignature) => None,
+                    Err(err) => {
+                        log::warn!("Invalid RSDP found at {:#x}: {:?}", maybe_rsdp_phys_start, err);
+                        None
+                    }
+                }
+            })
+        });
+
+        match rsdp_address {
+            Some(address) => {
+                let rsdp_mapping = unsafe { handler.map_physical_region::<Rsdp>(address, mem::size_of::<Rsdp>()) };
+                Ok(rsdp_mapping)
+            }
+            None => Err(AcpiError::NoValidRsdp),
+        }
+    }
+
+    /// Checks that:
+    ///     1) The signature is correct
+    ///     2) The checksum is correct
+    ///     3) For Version 2.0+, that the extension checksum is correct
+    pub fn validate(&self) -> AcpiResult<()> {
+        // Check the signature
+        if self.signature != RSDP_SIGNATURE {
+            return Err(AcpiError::RsdpIncorrectSignature);
+        }
+
+        // Check the OEM id is valid UTF8 (allows use of unwrap)
+        if str::from_utf8(&self.oem_id).is_err() {
+            return Err(AcpiError::RsdpInvalidOemId);
+        }
+
+        /*
+         * `self.length` doesn't exist on ACPI version 1.0, so we mustn't rely on it. Instead,
+         * check for version 1.0 and use a hard-coded length instead.
+         */
+        let length = if self.revision > 0 {
+            // For Version 2.0+, include the number of bytes specified by `length`
+            self.length as usize
+        } else {
+            RSDP_V1_LENGTH
+        };
+
+        let bytes = unsafe { slice::from_raw_parts(self as *const Rsdp as *const u8, length) };
+        let sum = bytes.iter().fold(0u8, |sum, &byte| sum.wrapping_add(byte));
+
+        if sum != 0 {
+            return Err(AcpiError::RsdpInvalidChecksum);
+        }
+
+        Ok(())
+    }
+
+    pub fn signature(&self) -> [u8; 8] {
+        self.signature
+    }
+
+    pub fn checksum(&self) -> u8 {
+        self.checksum
+    }
+
+    pub fn oem_id(&self) -> &str {
+        str::from_utf8(&self.oem_id).unwrap()
+    }
+
+    pub fn revision(&self) -> u8 {
+        self.revision
+    }
+
+    pub fn rsdt_address(&self) -> u32 {
+        self.rsdt_address
+    }
+
+    pub fn length(&self) -> u32 {
+        assert!(self.revision > 0, "Tried to read extended RSDP field with ACPI Version 1.0");
+        self.length
+    }
+
+    pub fn xsdt_address(&self) -> u64 {
+        assert!(self.revision > 0, "Tried to read extended RSDP field with ACPI Version 1.0");
+        self.xsdt_address
+    }
+
+    pub fn ext_checksum(&self) -> u8 {
+        assert!(self.revision > 0, "Tried to read extended RSDP field with ACPI Version 1.0");
+        self.ext_checksum
+    }
+}
+
+/// Find the areas we should search for the RSDP in.
+pub fn find_search_areas<H>(handler: H) -> [Range<usize>; 2]
+where
+    H: AcpiHandler,
+{
+    /*
+     * Read the base address of the EBDA from its location in the BDA (BIOS Data Area). Not all BIOSs fill this out
+     * unfortunately, so we might not get a sensible result. We shift it left 4, as it's a segment address.
+     */
+    let ebda_start_mapping =
+        unsafe { handler.map_physical_region::<u16>(EBDA_START_SEGMENT_PTR, mem::size_of::<u16>()) };
+    let ebda_start = (*ebda_start_mapping as usize) << 4;
+
+    [
+        /*
+         * The main BIOS area below 1MiB. In practice, from my [Restioson's] testing, the RSDP is more often here
+         * than the EBDA. We also don't want to search the entire possibele EBDA range, if we've failed to find it
+         * from the BDA.
+         */
+        RSDP_BIOS_AREA_START..(RSDP_BIOS_AREA_END + 1),
+        // Check if base segment ptr is in valid range for EBDA base
+        if (EBDA_EARLIEST_START..EBDA_END).contains(&ebda_start) {
+            // First KiB of EBDA
+            ebda_start..ebda_start + 1024
+        } else {
+            // We don't know where the EBDA starts, so just search the largest possible EBDA
+            EBDA_EARLIEST_START..(EBDA_END + 1)
+        },
+    ]
+}
+
+/// This (usually!) contains the base address of the EBDA (Extended Bios Data Area), shifted right by 4
+const EBDA_START_SEGMENT_PTR: usize = 0x40e;
+/// The earliest (lowest) memory address an EBDA (Extended Bios Data Area) can start
+const EBDA_EARLIEST_START: usize = 0x80000;
+/// The end of the EBDA (Extended Bios Data Area)
+const EBDA_END: usize = 0x9ffff;
+/// The start of the main BIOS area below 1MiB in which to search for the RSDP (Root System Description Pointer)
+const RSDP_BIOS_AREA_START: usize = 0xe0000;
+/// The end of the main BIOS area below 1MiB in which to search for the RSDP (Root System Description Pointer)
+const RSDP_BIOS_AREA_END: usize = 0xfffff;
+/// The RSDP (Root System Description Pointer)'s signature, "RSD PTR " (note trailing space)
+const RSDP_SIGNATURE: [u8; 8] = *b"RSD PTR ";