fix: Fix up README and the info example

Cargo.toml

@@ -8,7 +8,7 @@ repository = "https://github.com/repnop/fdt"
 
 license = "MPL-2.0"
 
-description = "A pure-Rust crate for parsing Flattened Devicetrees"
+description = "A pure-Rust `#![no_std]` crate for parsing Flattened Devicetrees"
 keywords = ["devicetree", "fdt", "dt"]
 categories = ["embedded", "no-std"]
 readme = "README.md"

README.md

@@ -1,6 +1,6 @@
 # `fdt`
 
-A pure-Rust crate for parsing Flattened Devicetrees, with the goal of having a
+A pure-Rust `#![no_std]` crate for parsing Flattened Devicetrees, with the goal of having a
 very ergonomic and idiomatic API.
 
 [![crates.io](https://img.shields.io/crates/v/fdt.svg)](https://crates.io/crates/fdt) [![Documentation](https://docs.rs/fdt/badge.svg)](https://docs.rs/fdt) ![Build](https://github.com/repnop/fdt/actions/workflows/test.yml/badge.svg?branch=master&event=push)
@@ -12,12 +12,35 @@ This crate is licensed under the Mozilla Public License 2.0 (see the LICENSE fil
 ## Example
 
 ```rust
-static MY_FDT: &[u8] = include_bytes!("my_fdt.dtb");
+static MY_FDT: &[u8] = include_bytes!("../test.dtb");
 
 fn main() {
     let fdt = fdt::Fdt::new(MY_FDT).unwrap();
 
     println!("This is a devicetree representation of a {}", fdt.root().model());
-    println!("...Which is compatible with: {}", fdt.root().compatible().join(","));
+    println!("...which is compatible with at least: {}", fdt.root().compatible().first());
+    println!("...and has {} CPU(s)", fdt.cpus().count());
+    println!(
+        "...and has at least one memory location at: {:#X}\n",
+        fdt.memory().regions().next().unwrap().starting_address as usize
+    );
+
+    let chosen = fdt.chosen();
+    if let Some(bootargs) = chosen.bootargs() {
+        println!("The bootargs are: {:?}", bootargs);
+    }
+
+    if let Some(stdout) = chosen.stdout() {
+        println!("It would write stdout to: {}", stdout.name);
+    }
+
+    let soc = fdt.find_node("/soc");
+    println!("Does it have a `/soc` node? {}", if soc.is_some() { "yes" } else { "no" });
+    if let Some(soc) = soc {
+        println!("...and it has the following children:");
+        for child in soc.children() {
+            println!("    {}", child.name);
+        }
+    }
 }
 ```

examples/basic_info.rs

@@ -5,18 +5,27 @@ fn main() {
 
     println!("This is a devicetree representation of a {}", fdt.root().model());
     println!("...which is compatible with at least: {}", fdt.root().compatible().first());
+    println!("...and has {} CPU(s)", fdt.cpus().count());
     println!(
         "...and has at least one memory location at: {:#X}\n",
         fdt.memory().regions().next().unwrap().starting_address as usize
     );
 
     let chosen = fdt.chosen();
-
     if let Some(bootargs) = chosen.bootargs() {
         println!("The bootargs are: {:?}", bootargs);
     }
 
     if let Some(stdout) = chosen.stdout() {
-        println!("It would write to: {}", stdout.name);
+        println!("It would write stdout to: {}", stdout.name);
+    }
+
+    let soc = fdt.find_node("/soc");
+    println!("Does it have a `/soc` node? {}", if soc.is_some() { "yes" } else { "no" });
+    if let Some(soc) = soc {
+        println!("...and it has the following children:");
+        for child in soc.children() {
+            println!("    {}", child.name);
+        }
     }
 }

src/lib.rs

@@ -2,6 +2,53 @@
 // v. 2.0. If a copy of the MPL was not distributed with this file, You can
 // obtain one at https://mozilla.org/MPL/2.0/.
 
+//! # `fdt`
+//!
+//! A pure-Rust `#![no_std]` crate for parsing Flattened Devicetrees, with the goal of having a
+//! very ergonomic and idiomatic API.
+//!
+//! [![crates.io](https://img.shields.io/crates/v/fdt.svg)](https://crates.io/crates/fdt) [![Documentation](https://docs.rs/fdt/badge.svg)](https://docs.rs/fdt) ![Build](https://github.com/repnop/fdt/actions/workflows/test.yml/badge.svg?branch=master&event=push)
+//!
+//! ## License
+//!
+//! This crate is licensed under the Mozilla Public License 2.0 (see the LICENSE file).
+//!
+//! ## Example
+//!
+//! ```rust,no_run
+//! static MY_FDT: &[u8] = include_bytes!("../test.dtb");
+//!
+//! fn main() {
+//!     let fdt = fdt::Fdt::new(MY_FDT).unwrap();
+//!
+//!     println!("This is a devicetree representation of a {}", fdt.root().model());
+//!     println!("...which is compatible with at least: {}", fdt.root().compatible().first());
+//!     println!("...and has {} CPU(s)", fdt.cpus().count());
+//!     println!(
+//!         "...and has at least one memory location at: {:#X}\n",
+//!         fdt.memory().regions().next().unwrap().starting_address as usize
+//!     );
+//!
+//!     let chosen = fdt.chosen();
+//!     if let Some(bootargs) = chosen.bootargs() {
+//!         println!("The bootargs are: {:?}", bootargs);
+//!     }
+//!
+//!     if let Some(stdout) = chosen.stdout() {
+//!         println!("It would write stdout to: {}", stdout.name);
+//!     }
+//!
+//!     let soc = fdt.find_node("/soc");
+//!     println!("Does it have a `/soc` node? {}", if soc.is_some() { "yes" } else { "no" });
+//!     if let Some(soc) = soc {
+//!         println!("...and it has the following children:");
+//!         for child in soc.children() {
+//!             println!("    {}", child.name);
+//!         }
+//!     }
+//! }
+//! ```
+
 #![no_std]
 
 #[cfg(test)]
@@ -109,6 +156,9 @@ impl FdtHeader {
 
 impl<'a> Fdt<'a> {
     /// Construct a new `Fdt` from a byte buffer
+    ///
+    /// Note: this function does ***not*** require that the data be 4-byte
+    /// aligned
     pub fn new(data: &'a [u8]) -> Result<Self, FdtError> {
         let mut stream = FdtData::new(data);
         let header = FdtHeader::from_bytes(&mut stream).ok_or(FdtError::BufferTooSmall)?;
@@ -125,6 +175,9 @@ impl<'a> Fdt<'a> {
     /// # Safety
     /// This function performs a read to verify the magic value. If the pointer
     /// is invalid this can result in undefined behavior.
+    ///
+    /// Note: this function does ***not*** require that the data be 4-byte
+    /// aligned
     pub unsafe fn from_ptr(ptr: *const u8) -> Result<Self, FdtError> {
         if ptr.is_null() {
             return Err(FdtError::BadPtr);