|
@@ -1,3 +1,31 @@
|
|
|
+//! `aml_parser` is a pure-Rust AML (ACPI Machine Language) parser, used for parsing the DSDT and
|
|
|
+//! SSDT tables from ACPI. This crate can be used by kernels to gather information about the
|
|
|
+//! hardware, and invoke control methods (this is not yet supported) to query and change the state
|
|
|
+//! of devices in a hardware-independent way.
|
|
|
+//!
|
|
|
+//! ### Using the library
|
|
|
+//! To use the library, you will mostly interact with the `AmlContext` type. You should create an
|
|
|
+//! instance of this type using `AmlContext::new()`, and then pass it tables containing AML
|
|
|
+//! (probably from the `acpi` crate), which you've mapped into the virtual address space. This will
|
|
|
+//! parse the table, populating the namespace with objects encoded by the AML. After this, you may
|
|
|
+//! unmap the memory the table was mapped into - all the information needed will be extracted and
|
|
|
+//! allocated on the heap.
|
|
|
+//!
|
|
|
+//! ### About the parser
|
|
|
+//! The parser is written using a set of custom parser combinators - the code can be confusing on
|
|
|
+//! first reading, but provides an extensible and type-safe way to write parsers. For an easy
|
|
|
+//! introduction to parser combinators and the foundations used for this library, I suggest reading
|
|
|
+//! [Bodil's fantastic blog post](https://bodil.lol/parser-combinators/).
|
|
|
+//!
|
|
|
+//! The actual combinators can be found in `parser.rs`. Various tricks are used to provide a nice
|
|
|
+//! API and work around limitations in the type system, such as the concrete types like
|
|
|
+//! `MapWithContext`, and the `make_parser_concrete` hack macro.
|
|
|
+//!
|
|
|
+//! The actual parsers are then grouped into categories based loosely on the AML grammar sections in
|
|
|
+//! the ACPI spec. Most are written in terms of combinators, but some have to be written in a more
|
|
|
+//! imperitive style, either because they're clearer, or because we haven't yet found good
|
|
|
+//! combinator patterns to express the parse.
|
|
|
+
|
|
|
#![no_std]
|
|
|
#![feature(decl_macro, type_ascription, box_syntax)]
|
|
|
|
|
@@ -19,7 +47,7 @@ pub mod value;
|
|
|
pub use crate::value::AmlValue;
|
|
|
|
|
|
use alloc::collections::BTreeMap;
|
|
|
-use log::{error, trace};
|
|
|
+use log::error;
|
|
|
use name_object::AmlName;
|
|
|
use parser::Parser;
|
|
|
use pkg_length::PkgLength;
|
|
@@ -66,6 +94,8 @@ impl AmlContext {
|
|
|
error!("Failed to parse AML stream. Err = {:?}", err);
|
|
|
Err(err)
|
|
|
}
|
|
|
+ }
|
|
|
+ }
|
|
|
|
|
|
/// Resolves a given path relative to the current scope (if the given path is not absolute).
|
|
|
/// The returned path can be used to index the namespace.
|