Add some basic documentation about the library

aml_parser/src/lib.rs

@@ -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.

aml_parser/src/term_object.rs

@@ -21,7 +21,6 @@ use crate::{
 };
 use alloc::{string::String, vec::Vec};
 use core::str;
-use log::trace;
 
 /// `TermList`s are usually found within explicit-length objects (so they have a `PkgLength`
 /// elsewhere in the structure), so this takes a number of bytes to parse.