src/lib.rs - platform/external/rust/crates/acpi - Git at Google

 //! A library for parsing ACPI tables. This crate can be used by bootloaders and kernels for architectures that
 //! support ACPI. This crate is not feature-complete, but can parse lots of the more common tables. Parsing the
 //! ACPI tables is required for correctly setting up the APICs, HPET, and provides useful information about power
 //! management and many other platform capabilities.
 //!
 //! This crate is designed to find and parse the static tables ACPI provides. It should be used in conjunction with
 //! the `aml` crate, which is the (much less complete) AML parser used to parse the DSDT and SSDTs. These crates
 //! are separate because some kernels may want to detect the static tables, but delay AML parsing to a later stage.
 //!
 //! This crate can be used in three configurations, depending on the environment it's being used from:
 //!    - **Without allocator support** - this can be achieved by disabling the `allocator_api` and `alloc`
 //!      features. The core parts of the library will still be usable, but with generally reduced functionality
 //!      and ease-of-use.
 //!    - **With a custom allocator** - by disabling just the `alloc` feature, you can use the `new_in` functions to
 //!      access increased functionality with your own allocator. This allows `acpi` to be integrated more closely
 //!      with environments that already provide a custom allocator, for example to gracefully handle allocation
 //!      errors.
 //!    - **With the globally-set allocator** - the `alloc` feature provides `new` functions that simply use the
 //!      global allocator. This is the easiest option, and the one the majority of users will want. It is the
 //!      default configuration of the crate.
 //!
 //! ### Usage
 //! To use the library, you will need to provide an implementation of the `AcpiHandler` trait, which allows the
 //! library to make requests such as mapping a particular region of physical memory into the virtual address space.
 //!
 //! You then need to construct an instance of `AcpiTables`, which can be done in a few ways depending on how much
 //! information you have:
 //! * Use `AcpiTables::from_rsdp` if you have the physical address of the RSDP
 //! * Use `AcpiTables::from_rsdt` if you have the physical address of the RSDT/XSDT
 //! * Use `AcpiTables::search_for_rsdp_bios` if you don't have the address of either, but **you know you are
 //! running on BIOS, not UEFI**
 //! * Use `AcpiTables::from_tables_direct` if you are using the library in an unusual setting, such as in usermode,
 //!   and have a custom method to enumerate and access the tables.
 //!
 //! `AcpiTables` stores the addresses of all of the tables detected on a platform. The SDTs are parsed by this
 //! library, or can be accessed directly with `from_sdt`, while the `DSDT` and any `SSDTs` should be parsed with
 //! `aml`.
 //!
 //! To gather information out of the static tables, a few of the types you should take a look at are:
 //!    - [`PlatformInfo`](crate::platform::PlatformInfo) parses the FADT and MADT to create a nice view of the
 //!      processor topology and interrupt controllers on `x86_64`, and the interrupt controllers on other platforms.
 //!      `AcpiTables::platform_info` is a convenience method for constructing a `PlatformInfo`.
 //!    - [`HpetInfo`](crate::hpet::HpetInfo) parses the HPET table and tells you how to configure the High
 //!      Precision Event Timer.
 //!    - [`PciConfigRegions`](crate::mcfg::PciConfigRegions) parses the MCFG and tells you how PCIe configuration
 //!      space is mapped into physical memory.

 /*
  * Contributing notes (you may find these useful if you're new to contributing to the library):
  *    - Accessing packed fields without UB: Lots of the structures defined by ACPI are defined with `repr(packed)`
  *      to prevent padding being introduced, which would make the structure's layout incorrect. In Rust, this
  *      creates a problem as references to these fields could be unaligned, which is undefined behaviour. For the
  *      majority of these fields, this problem can be easily avoided by telling the compiler to make a copy of the
  *      field's contents: this is the perhaps unfamiliar pattern of e.g. `!{ entry.flags }.get_bit(0)` we use
  *      around the codebase.
  */

 #![no_std]
 #![deny(unsafe_op_in_unsafe_fn)]
 #![cfg_attr(feature = "allocator_api", feature(allocator_api))]

 #[cfg_attr(test, macro_use)]
 #[cfg(test)]
 extern crate std;

 #[cfg(feature = "alloc")]
 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")]
 mod managed_slice;
 #[cfg(feature = "allocator_api")]
 pub use managed_slice::*;

 #[cfg(feature = "allocator_api")]
 pub mod platform;
 #[cfg(feature = "allocator_api")]
 pub use crate::platform::{interrupt::InterruptModel, PlatformInfo};

 #[cfg(feature = "allocator_api")]
 pub use crate::mcfg::PciConfigRegions;

 pub use fadt::PowerProfile;
 pub use handler::{AcpiHandler, PhysicalMapping};
 pub use hpet::HpetInfo;
 pub use madt::MadtError;

 use crate::sdt::{SdtHeader, Signature};
 use core::mem;
 use rsdp::Rsdp;

 /// Result type used by error-returning functions.
 pub type AcpiResult<T> = core::result::Result<T, AcpiError>;

 /// All types representing ACPI tables should implement this trait.
 ///
 /// ### Safety
 ///
 /// The table's memory is naively interpreted, so you must be careful in providing a type that
 /// correctly represents the table's structure. Regardless of the provided type's size, the region mapped will
 /// be the size specified in the SDT's header. Providing a table impl that is larger than this, *may* lead to
 /// page-faults, aliasing references, or derefencing uninitialized memory (the latter two being UB).
 /// This isn't forbidden, however, because some tables rely on the impl being larger than a provided SDT in some
 /// versions of ACPI (the [`ExtendedField`](crate::sdt::ExtendedField) type will be useful if you need to do
 /// this. See our [`Fadt`](crate::fadt::Fadt) type for an example of this).
 pub unsafe trait AcpiTable {
     const SIGNATURE: Signature;

     fn header(&self) -> &sdt::SdtHeader;

     fn validate(&self) -> AcpiResult<()> {
         self.header().validate(Self::SIGNATURE)
     }
 }

 /// Error type used by functions that return an `AcpiResult<T>`.
 #[derive(Debug)]
 pub enum AcpiError {
     NoValidRsdp,
     RsdpIncorrectSignature,
     RsdpInvalidOemId,
     RsdpInvalidChecksum,

     SdtInvalidSignature(Signature),
     SdtInvalidOemId(Signature),
     SdtInvalidTableId(Signature),
     SdtInvalidChecksum(Signature),

     TableMissing(Signature),
     InvalidFacsAddress,
     InvalidDsdtAddress,
     InvalidMadt(MadtError),
     InvalidGenericAddress,

     AllocError,
 }

 /// Type capable of enumerating the existing ACPI tables on the system.
 ///
 ///
 /// ### Implementation Note
 ///
 /// 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>,
     revision: u8,
     handler: H,
 }

 impl<H> AcpiTables<H>
 where
     H: AcpiHandler,
 {
     /// Create an `AcpiTables` if you have the physical address of the RSDP.
     ///
     /// ### 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()?;

         // Safety: RSDP has been validated.
         unsafe { Self::from_validated_rsdp(handler, rsdp_mapping) }
     }

     /// Search for the RSDP on a BIOS platform. This accesses BIOS-specific memory locations and will probably not
     /// 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())? };
         // Safety: RSDP has been validated from `Rsdp::search_for_on_bios`
         unsafe { Self::from_validated_rsdp(handler, rsdp_mapping) }
     }

     /// Create an `AcpiTables` if you have a `PhysicalMapping` of the RSDP that you know is correct. This is called
     /// from `from_rsdp` after validation, but can also be used if you've searched for the RSDP manually on a BIOS
     /// system.
     ///
     /// ### Safety: Caller must ensure that the provided mapping is a fully validated RSDP.
     pub unsafe fn from_validated_rsdp(handler: H, rsdp_mapping: PhysicalMapping<H, Rsdp>) -> AcpiResult<Self> {
         macro_rules! read_root_table {
             ($signature_name:ident, $address_getter:ident) => {{
                 #[repr(transparent)]
                 struct RootTable {
                     header: SdtHeader,
                 }

                 unsafe impl AcpiTable for RootTable {
                     const SIGNATURE: Signature = Signature::$signature_name;

                     fn header(&self) -> &SdtHeader {
                         &self.header
                     }
                 }

                 // Unmap RSDP as soon as possible
                 let table_phys_start = rsdp_mapping.$address_getter() as usize;
                 drop(rsdp_mapping);

                 // Map and validate root table
                 // 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
                 // Avoid requesting table unmap twice (from both original and converted `table_mapping`s)
                 let table_mapping = mem::ManuallyDrop::new(table_mapping);
                 // SAFETY: `SdtHeader` is equivalent to `Sdt` memory-wise
                 let table_mapping = unsafe {
                     PhysicalMapping::new(
                         table_mapping.physical_start(),
                         table_mapping.virtual_start().cast::<SdtHeader>(),
                         table_mapping.region_length(),
                         table_mapping.mapped_length(),
                         handler.clone(),
                     )
                 };

                 table_mapping
             }};
         }

         let revision = rsdp_mapping.revision();
         let root_table_mapping = if revision == 0 {
             /*
              * We're running on ACPI Version 1.0. We should use the 32-bit RSDT address.
              */

             read_root_table!(RSDT, rsdt_address)
         } else {
             /*
              * We're running on ACPI Version 2.0+. We should use the 64-bit XSDT address, truncated
              * to 32 bits on x86.
              */

             read_root_table!(XSDT, xsdt_address)
         };

         Ok(Self { mapping: root_table_mapping, revision, handler })
     }

     /// The ACPI revision of the tables enumerated by this structure.
     #[inline]
     pub const fn revision(&self) -> u8 {
         self.revision
     }

     /// Constructs a [`TablesPhysPtrsIter`] over this table.
     fn tables_phys_ptrs(&self) -> TablesPhysPtrsIter<'_> {
         // SAFETY: The virtual address of the array of pointers follows the virtual address of the table in memory.
         let ptrs_virt_start = unsafe { self.mapping.virtual_start().as_ptr().add(1).cast::<u8>() };
         let ptrs_bytes_len = self.mapping.region_length() - mem::size_of::<SdtHeader>();
         // SAFETY: `ptrs_virt_start` points to an array of `ptrs_bytes_len` bytes that lives as long as `self`.
         let ptrs_bytes = unsafe { core::slice::from_raw_parts(ptrs_virt_start, ptrs_bytes_len) };
         let ptr_size = if self.revision == 0 {
             4 // RSDT entry size
         } else {
             8 // XSDT entry size
         };

         ptrs_bytes.chunks(ptr_size).map(|ptr_bytes_src| {
             // Construct a native pointer using as many bytes as required from `ptr_bytes_src` (note that ACPI is
             // little-endian)

             let mut ptr_bytes_dst = [0; mem::size_of::<usize>()];
             let common_ptr_size = usize::min(mem::size_of::<usize>(), ptr_bytes_src.len());
             ptr_bytes_dst[..common_ptr_size].copy_from_slice(&ptr_bytes_src[..common_ptr_size]);

             usize::from_le_bytes(ptr_bytes_dst) as *const SdtHeader
         })
     }

     /// Searches through the ACPI table headers and attempts to locate the table with a matching `T::SIGNATURE`.
     pub fn find_table<T: AcpiTable>(&self) -> AcpiResult<PhysicalMapping<H, T>> {
         self.tables_phys_ptrs()
             .find_map(|table_phys_ptr| {
                 // SAFETY: Table guarantees its contained addresses to be valid.
                 match unsafe { read_table(self.handler.clone(), table_phys_ptr as usize) } {
                     Ok(table_mapping) => Some(table_mapping),
                     Err(AcpiError::SdtInvalidSignature(_)) => None,
                     Err(e) => {
                         log::warn!(
                             "Found invalid {} table at physical address {:p}: {:?}",
                             T::SIGNATURE,
                             table_phys_ptr,
                             e
                         );

                         None
                     }
                 }
             })
             .ok_or(AcpiError::TableMissing(T::SIGNATURE))
     }

     /// Finds and returns the DSDT AML table, if it exists.
     pub fn dsdt(&self) -> AcpiResult<AmlTable> {
         self.find_table::<fadt::Fadt>().and_then(|fadt| {
             #[repr(transparent)]
             struct Dsdt {
                 header: SdtHeader,
             }

             // Safety: Implementation properly represents a valid DSDT.
             unsafe impl AcpiTable for Dsdt {
                 const SIGNATURE: Signature = Signature::DSDT;

                 fn header(&self) -> &SdtHeader {
                     &self.header
                 }
             }

             let dsdt_address = fadt.dsdt_address()?;
             let dsdt = unsafe { read_table::<H, Dsdt>(self.handler.clone(), dsdt_address)? };

             Ok(AmlTable::new(dsdt_address, dsdt.header().length))
         })
     }

     /// Iterates through all of the SSDT tables.
     pub fn ssdts(&self) -> SsdtIterator<H> {
         SsdtIterator { tables_phys_ptrs: self.tables_phys_ptrs(), handler: self.handler.clone() }
     }

     /// Convenience method for contructing a [`PlatformInfo`](crate::platform::PlatformInfo). This is one of the
     /// first things you should usually do with an `AcpiTables`, and allows to collect helpful information about
     /// the platform from the ACPI tables.
     ///
     /// Like `platform_info_in`, but uses the global allocator.
     #[cfg(feature = "alloc")]
     pub fn platform_info(&self) -> AcpiResult<PlatformInfo<alloc::alloc::Global>> {
         PlatformInfo::new(self)
     }

     /// Convenience method for contructing a [`PlatformInfo`](crate::platform::PlatformInfo). This is one of the
     /// first things you should usually do with an `AcpiTables`, and allows to collect helpful information about
     /// the platform from the ACPI tables.
     #[cfg(feature = "allocator_api")]
     pub fn platform_info_in<A>(&self, allocator: A) -> AcpiResult<PlatformInfo<A>>
     where
         A: core::alloc::Allocator + Clone,
     {
         PlatformInfo::new_in(self, allocator)
     }
 }

 #[derive(Debug)]
 pub struct Sdt {
     /// Physical address of the start of the SDT, including the header.
     pub physical_address: usize,
     /// Length of the table in bytes.
     pub length: u32,
     /// Whether this SDT has been validated. This is set to `true` the first time it is mapped and validated.
     pub validated: bool,
 }

 /// An iterator over the physical table addresses in an RSDT or XSDT.
 type TablesPhysPtrsIter<'t> = core::iter::Map<core::slice::Chunks<'t, u8>, fn(&[u8]) -> *const SdtHeader>;

 #[derive(Debug)]
 pub struct AmlTable {
     /// Physical address of the start of the AML stream (excluding the table header).
     pub address: usize,
     /// Length (in bytes) of the AML stream.
     pub length: u32,
 }

 impl AmlTable {
     /// Create an `AmlTable` from the address and length of the table **including the SDT header**.
     pub(crate) fn new(address: usize, length: u32) -> AmlTable {
         AmlTable {
             address: address + mem::size_of::<SdtHeader>(),
             length: length - mem::size_of::<SdtHeader>() as u32,
         }
     }
 }

 /// ### Safety: Caller must ensure the provided address is valid for being read as an `SdtHeader`.
 unsafe fn read_table<H: AcpiHandler, T: AcpiTable>(
     handler: H,
     address: usize,
 ) -> AcpiResult<PhysicalMapping<H, T>> {
     // Attempt to peek at the SDT header to correctly enumerate the entire table.

     // SAFETY: `address` needs to be valid for the size of `SdtHeader`, or the ACPI tables are malformed (not a
     // software issue).
     let header_mapping = unsafe { handler.map_physical_region::<SdtHeader>(address, mem::size_of::<SdtHeader>()) };

     SdtHeader::validate_lazy(header_mapping, handler)
 }

 /// Iterator that steps through all of the tables, and returns only the SSDTs as `AmlTable`s.
 pub struct SsdtIterator<'t, H>
 where
     H: AcpiHandler,
 {
     tables_phys_ptrs: TablesPhysPtrsIter<'t>,
     handler: H,
 }

 impl<'t, H> Iterator for SsdtIterator<'t, H>
 where
     H: AcpiHandler,
 {
     type Item = AmlTable;

     fn next(&mut self) -> Option<Self::Item> {
         #[repr(transparent)]
         struct Ssdt {
             header: SdtHeader,
         }

         // SAFETY: Implementation properly represents a valid SSDT.
         unsafe impl AcpiTable for Ssdt {
             const SIGNATURE: Signature = Signature::SSDT;

             fn header(&self) -> &SdtHeader {
                 &self.header
             }
         }

         // Borrow single field for closure to avoid immutable reference to `self` that inhibits `find_map`
         let handler = &self.handler;

         // Consume iterator until next valid SSDT and return the latter
         self.tables_phys_ptrs.find_map(|table_phys_ptr| {
             // SAFETY: Table guarantees its contained addresses to be valid.
             match unsafe { read_table::<_, Ssdt>(handler.clone(), table_phys_ptr as usize) } {
                 Ok(ssdt_mapping) => Some(AmlTable::new(ssdt_mapping.physical_start(), ssdt_mapping.header.length)),
                 Err(AcpiError::SdtInvalidSignature(_)) => None,
                 Err(e) => {
                     log::warn!("Found invalid SSDT at physical address {:p}: {:?}", table_phys_ptr, e);

                     None
                 }
             }
         })
     }
 }
	//! A library for parsing ACPI tables. This crate can be used by bootloaders and kernels for architectures that
	//! support ACPI. This crate is not feature-complete, but can parse lots of the more common tables. Parsing the
	//! ACPI tables is required for correctly setting up the APICs, HPET, and provides useful information about power
	//! management and many other platform capabilities.
	//!
	//! This crate is designed to find and parse the static tables ACPI provides. It should be used in conjunction with
	//! the `aml` crate, which is the (much less complete) AML parser used to parse the DSDT and SSDTs. These crates
	//! are separate because some kernels may want to detect the static tables, but delay AML parsing to a later stage.
	//!
	//! This crate can be used in three configurations, depending on the environment it's being used from:
	//! - Without allocator support - this can be achieved by disabling the `allocator_api` and `alloc`
	//! features. The core parts of the library will still be usable, but with generally reduced functionality
	//! and ease-of-use.
	//! - With a custom allocator - by disabling just the `alloc` feature, you can use the `new_in` functions to
	//! access increased functionality with your own allocator. This allows `acpi` to be integrated more closely
	//! with environments that already provide a custom allocator, for example to gracefully handle allocation
	//! errors.
	//! - With the globally-set allocator - the `alloc` feature provides `new` functions that simply use the
	//! global allocator. This is the easiest option, and the one the majority of users will want. It is the
	//! default configuration of the crate.
	//!
	//! ### Usage
	//! To use the library, you will need to provide an implementation of the `AcpiHandler` trait, which allows the
	//! library to make requests such as mapping a particular region of physical memory into the virtual address space.
	//!
	//! You then need to construct an instance of `AcpiTables`, which can be done in a few ways depending on how much
	//! information you have:
	//! * Use `AcpiTables::from_rsdp` if you have the physical address of the RSDP
	//! * Use `AcpiTables::from_rsdt` if you have the physical address of the RSDT/XSDT
	//! * Use `AcpiTables::search_for_rsdp_bios` if you don't have the address of either, but **you know you are
	//! running on BIOS, not UEFI**
	//! * Use `AcpiTables::from_tables_direct` if you are using the library in an unusual setting, such as in usermode,
	//! and have a custom method to enumerate and access the tables.
	//!
	//! `AcpiTables` stores the addresses of all of the tables detected on a platform. The SDTs are parsed by this
	//! library, or can be accessed directly with `from_sdt`, while the `DSDT` and any `SSDTs` should be parsed with
	//! `aml`.
	//!
	//! To gather information out of the static tables, a few of the types you should take a look at are:
	//! - [`PlatformInfo`](crate::platform::PlatformInfo) parses the FADT and MADT to create a nice view of the
	//! processor topology and interrupt controllers on `x86_64`, and the interrupt controllers on other platforms.
	//! `AcpiTables::platform_info` is a convenience method for constructing a `PlatformInfo`.
	//! - [`HpetInfo`](crate::hpet::HpetInfo) parses the HPET table and tells you how to configure the High
	//! Precision Event Timer.
	//! - [`PciConfigRegions`](crate::mcfg::PciConfigRegions) parses the MCFG and tells you how PCIe configuration
	//! space is mapped into physical memory.

	/*
	* Contributing notes (you may find these useful if you're new to contributing to the library):
	* - Accessing packed fields without UB: Lots of the structures defined by ACPI are defined with `repr(packed)`
	* to prevent padding being introduced, which would make the structure's layout incorrect. In Rust, this
	* creates a problem as references to these fields could be unaligned, which is undefined behaviour. For the
	* majority of these fields, this problem can be easily avoided by telling the compiler to make a copy of the
	* field's contents: this is the perhaps unfamiliar pattern of e.g. `!{ entry.flags }.get_bit(0)` we use
	* around the codebase.
	*/

	#![no_std]
	#![deny(unsafe_op_in_unsafe_fn)]
	#![cfg_attr(feature = "allocator_api", feature(allocator_api))]

	#[cfg_attr(test, macro_use)]
	#[cfg(test)]
	extern crate std;

	#[cfg(feature = "alloc")]
	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")]
	mod managed_slice;
	#[cfg(feature = "allocator_api")]
	pub use managed_slice::*;

	#[cfg(feature = "allocator_api")]
	pub mod platform;
	#[cfg(feature = "allocator_api")]
	pub use crate::platform::{interrupt::InterruptModel, PlatformInfo};

	#[cfg(feature = "allocator_api")]
	pub use crate::mcfg::PciConfigRegions;

	pub use fadt::PowerProfile;
	pub use handler::{AcpiHandler, PhysicalMapping};
	pub use hpet::HpetInfo;
	pub use madt::MadtError;

	use crate::sdt::{SdtHeader, Signature};
	use core::mem;
	use rsdp::Rsdp;

	/// Result type used by error-returning functions.
	pub type AcpiResult<T> = core::result::Result<T, AcpiError>;

	/// All types representing ACPI tables should implement this trait.
	///
	/// ### Safety
	///
	/// The table's memory is naively interpreted, so you must be careful in providing a type that
	/// correctly represents the table's structure. Regardless of the provided type's size, the region mapped will
	/// be the size specified in the SDT's header. Providing a table impl that is larger than this, may lead to
	/// page-faults, aliasing references, or derefencing uninitialized memory (the latter two being UB).
	/// This isn't forbidden, however, because some tables rely on the impl being larger than a provided SDT in some
	/// versions of ACPI (the [`ExtendedField`](crate::sdt::ExtendedField) type will be useful if you need to do
	/// this. See our [`Fadt`](crate::fadt::Fadt) type for an example of this).
	pub unsafe trait AcpiTable {
	const SIGNATURE: Signature;

	fn header(&self) -> &sdt::SdtHeader;

	fn validate(&self) -> AcpiResult<()> {
	self.header().validate(Self::SIGNATURE)
	}
	}

	/// Error type used by functions that return an `AcpiResult<T>`.
	#[derive(Debug)]
	pub enum AcpiError {
	NoValidRsdp,
	RsdpIncorrectSignature,
	RsdpInvalidOemId,
	RsdpInvalidChecksum,

	SdtInvalidSignature(Signature),
	SdtInvalidOemId(Signature),
	SdtInvalidTableId(Signature),
	SdtInvalidChecksum(Signature),

	TableMissing(Signature),
	InvalidFacsAddress,
	InvalidDsdtAddress,
	InvalidMadt(MadtError),
	InvalidGenericAddress,

	AllocError,
	}

	/// Type capable of enumerating the existing ACPI tables on the system.
	///
	///
	/// ### Implementation Note
	///
	/// 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>,
	revision: u8,
	handler: H,
	}

	impl<H> AcpiTables<H>
	where
	H: AcpiHandler,
	{
	/// Create an `AcpiTables` if you have the physical address of the RSDP.
	///
	/// ### 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()?;

	// Safety: RSDP has been validated.
	unsafe { Self::from_validated_rsdp(handler, rsdp_mapping) }
	}

	/// Search for the RSDP on a BIOS platform. This accesses BIOS-specific memory locations and will probably not
	/// 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())? };
	// Safety: RSDP has been validated from `Rsdp::search_for_on_bios`
	unsafe { Self::from_validated_rsdp(handler, rsdp_mapping) }
	}

	/// Create an `AcpiTables` if you have a `PhysicalMapping` of the RSDP that you know is correct. This is called
	/// from `from_rsdp` after validation, but can also be used if you've searched for the RSDP manually on a BIOS
	/// system.
	///
	/// ### Safety: Caller must ensure that the provided mapping is a fully validated RSDP.
	pub unsafe fn from_validated_rsdp(handler: H, rsdp_mapping: PhysicalMapping<H, Rsdp>) -> AcpiResult<Self> {
	macro_rules! read_root_table {
	($signature_name:ident, $address_getter:ident) => {{
	#[repr(transparent)]
	struct RootTable {
	header: SdtHeader,
	}

	unsafe impl AcpiTable for RootTable {
	const SIGNATURE: Signature = Signature::$signature_name;

	fn header(&self) -> &SdtHeader {
	&self.header
	}
	}

	// Unmap RSDP as soon as possible
	let table_phys_start = rsdp_mapping.$address_getter() as usize;
	drop(rsdp_mapping);

	// Map and validate root table
	// 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
	// Avoid requesting table unmap twice (from both original and converted `table_mapping`s)
	let table_mapping = mem::ManuallyDrop::new(table_mapping);
	// SAFETY: `SdtHeader` is equivalent to `Sdt` memory-wise
	let table_mapping = unsafe {
	PhysicalMapping::new(
	table_mapping.physical_start(),
	table_mapping.virtual_start().cast::<SdtHeader>(),
	table_mapping.region_length(),
	table_mapping.mapped_length(),
	handler.clone(),
	)
	};

	table_mapping
	}};
	}

	let revision = rsdp_mapping.revision();
	let root_table_mapping = if revision == 0 {
	/*
	* We're running on ACPI Version 1.0. We should use the 32-bit RSDT address.
	*/

	read_root_table!(RSDT, rsdt_address)
	} else {
	/*
	* We're running on ACPI Version 2.0+. We should use the 64-bit XSDT address, truncated
	* to 32 bits on x86.
	*/

	read_root_table!(XSDT, xsdt_address)
	};

	Ok(Self { mapping: root_table_mapping, revision, handler })
	}

	/// The ACPI revision of the tables enumerated by this structure.
	#[inline]
	pub const fn revision(&self) -> u8 {
	self.revision
	}

	/// Constructs a [`TablesPhysPtrsIter`] over this table.
	fn tables_phys_ptrs(&self) -> TablesPhysPtrsIter<'_> {
	// SAFETY: The virtual address of the array of pointers follows the virtual address of the table in memory.
	let ptrs_virt_start = unsafe { self.mapping.virtual_start().as_ptr().add(1).cast::<u8>() };
	let ptrs_bytes_len = self.mapping.region_length() - mem::size_of::<SdtHeader>();
	// SAFETY: `ptrs_virt_start` points to an array of `ptrs_bytes_len` bytes that lives as long as `self`.
	let ptrs_bytes = unsafe { core::slice::from_raw_parts(ptrs_virt_start, ptrs_bytes_len) };
	let ptr_size = if self.revision == 0 {
	4 // RSDT entry size
	} else {
	8 // XSDT entry size
	};

	ptrs_bytes.chunks(ptr_size).map(\|ptr_bytes_src\| {
	// Construct a native pointer using as many bytes as required from `ptr_bytes_src` (note that ACPI is
	// little-endian)

	let mut ptr_bytes_dst = [0; mem::size_of::<usize>()];
	let common_ptr_size = usize::min(mem::size_of::<usize>(), ptr_bytes_src.len());
	ptr_bytes_dst[..common_ptr_size].copy_from_slice(&ptr_bytes_src[..common_ptr_size]);

	usize::from_le_bytes(ptr_bytes_dst) as *const SdtHeader
	})
	}

	/// Searches through the ACPI table headers and attempts to locate the table with a matching `T::SIGNATURE`.
	pub fn find_table<T: AcpiTable>(&self) -> AcpiResult<PhysicalMapping<H, T>> {
	self.tables_phys_ptrs()
	.find_map(\|table_phys_ptr\| {
	// SAFETY: Table guarantees its contained addresses to be valid.
	match unsafe { read_table(self.handler.clone(), table_phys_ptr as usize) } {
	Ok(table_mapping) => Some(table_mapping),
	Err(AcpiError::SdtInvalidSignature(_)) => None,
	Err(e) => {
	log::warn!(
	"Found invalid {} table at physical address {:p}: {:?}",
	T::SIGNATURE,
	table_phys_ptr,
	e
	);

	None
	}
	}
	})
	.ok_or(AcpiError::TableMissing(T::SIGNATURE))
	}

	/// Finds and returns the DSDT AML table, if it exists.
	pub fn dsdt(&self) -> AcpiResult<AmlTable> {
	self.find_table::<fadt::Fadt>().and_then(\|fadt\| {
	#[repr(transparent)]
	struct Dsdt {
	header: SdtHeader,
	}

	// Safety: Implementation properly represents a valid DSDT.
	unsafe impl AcpiTable for Dsdt {
	const SIGNATURE: Signature = Signature::DSDT;

	fn header(&self) -> &SdtHeader {
	&self.header
	}
	}

	let dsdt_address = fadt.dsdt_address()?;
	let dsdt = unsafe { read_table::<H, Dsdt>(self.handler.clone(), dsdt_address)? };

	Ok(AmlTable::new(dsdt_address, dsdt.header().length))
	})
	}

	/// Iterates through all of the SSDT tables.
	pub fn ssdts(&self) -> SsdtIterator<H> {
	SsdtIterator { tables_phys_ptrs: self.tables_phys_ptrs(), handler: self.handler.clone() }
	}

	/// Convenience method for contructing a [`PlatformInfo`](crate::platform::PlatformInfo). This is one of the
	/// first things you should usually do with an `AcpiTables`, and allows to collect helpful information about
	/// the platform from the ACPI tables.
	///
	/// Like `platform_info_in`, but uses the global allocator.
	#[cfg(feature = "alloc")]
	pub fn platform_info(&self) -> AcpiResult<PlatformInfo<alloc::alloc::Global>> {
	PlatformInfo::new(self)
	}

	/// Convenience method for contructing a [`PlatformInfo`](crate::platform::PlatformInfo). This is one of the
	/// first things you should usually do with an `AcpiTables`, and allows to collect helpful information about
	/// the platform from the ACPI tables.
	#[cfg(feature = "allocator_api")]
	pub fn platform_info_in<A>(&self, allocator: A) -> AcpiResult<PlatformInfo<A>>
	where
	A: core::alloc::Allocator + Clone,
	{
	PlatformInfo::new_in(self, allocator)
	}
	}

	#[derive(Debug)]
	pub struct Sdt {
	/// Physical address of the start of the SDT, including the header.
	pub physical_address: usize,
	/// Length of the table in bytes.
	pub length: u32,
	/// Whether this SDT has been validated. This is set to `true` the first time it is mapped and validated.
	pub validated: bool,
	}

	/// An iterator over the physical table addresses in an RSDT or XSDT.
	type TablesPhysPtrsIter<'t> = core::iter::Map<core::slice::Chunks<'t, u8>, fn(&[u8]) -> *const SdtHeader>;

	#[derive(Debug)]
	pub struct AmlTable {
	/// Physical address of the start of the AML stream (excluding the table header).
	pub address: usize,
	/// Length (in bytes) of the AML stream.
	pub length: u32,
	}

	impl AmlTable {
	/// Create an `AmlTable` from the address and length of the table including the SDT header.
	pub(crate) fn new(address: usize, length: u32) -> AmlTable {
	AmlTable {
	address: address + mem::size_of::<SdtHeader>(),
	length: length - mem::size_of::<SdtHeader>() as u32,
	}
	}
	}

	/// ### Safety: Caller must ensure the provided address is valid for being read as an `SdtHeader`.
	unsafe fn read_table<H: AcpiHandler, T: AcpiTable>(
	handler: H,
	address: usize,
	) -> AcpiResult<PhysicalMapping<H, T>> {
	// Attempt to peek at the SDT header to correctly enumerate the entire table.

	// SAFETY: `address` needs to be valid for the size of `SdtHeader`, or the ACPI tables are malformed (not a
	// software issue).
	let header_mapping = unsafe { handler.map_physical_region::<SdtHeader>(address, mem::size_of::<SdtHeader>()) };

	SdtHeader::validate_lazy(header_mapping, handler)
	}

	/// Iterator that steps through all of the tables, and returns only the SSDTs as `AmlTable`s.
	pub struct SsdtIterator<'t, H>
	where
	H: AcpiHandler,
	{
	tables_phys_ptrs: TablesPhysPtrsIter<'t>,
	handler: H,
	}

	impl<'t, H> Iterator for SsdtIterator<'t, H>
	where
	H: AcpiHandler,
	{
	type Item = AmlTable;

	fn next(&mut self) -> Option<Self::Item> {
	#[repr(transparent)]
	struct Ssdt {
	header: SdtHeader,
	}

	// SAFETY: Implementation properly represents a valid SSDT.
	unsafe impl AcpiTable for Ssdt {
	const SIGNATURE: Signature = Signature::SSDT;

	fn header(&self) -> &SdtHeader {
	&self.header
	}
	}

	// Borrow single field for closure to avoid immutable reference to `self` that inhibits `find_map`
	let handler = &self.handler;

	// Consume iterator until next valid SSDT and return the latter
	self.tables_phys_ptrs.find_map(\|table_phys_ptr\| {
	// SAFETY: Table guarantees its contained addresses to be valid.
	match unsafe { read_table::<_, Ssdt>(handler.clone(), table_phys_ptr as usize) } {
	Ok(ssdt_mapping) => Some(AmlTable::new(ssdt_mapping.physical_start(), ssdt_mapping.header.length)),
	Err(AcpiError::SdtInvalidSignature(_)) => None,
	Err(e) => {
	log::warn!("Found invalid SSDT at physical address {:p}: {:?}", table_phys_ptr, e);

	None
	}
	}
	})
	}
	}