Add in-memory Device Tree representation

Cargo.toml

@@ -15,8 +15,11 @@ keywords = ["device-tree", "fdt", "dtb", "dts", "parser", "no_std"]
 default = []
 alloc = []
 std = ["alloc"]
+write = ["alloc", "dep:indexmap", "dep:twox-hash"]
 
 [dependencies]
+indexmap = { version = "2", optional = true, default-features = false }
+twox-hash = { version = "2", optional = true, features = ["xxhash64"], default-features = false }
 zerocopy = { version = "0.8.28", features = ["derive"] }
 
 [lints.rust]

src/fdt/mod.rs

@@ -375,7 +375,11 @@ impl<'a> Fdt<'a> {
     /// # Performance
     ///
     /// This method traverses the device tree and its performance is linear in
-    /// the number of nodes in the path.
+    /// the number of nodes in the path. If you need to call this often,
+    /// consider using
+    /// [`DeviceTree::from_fdt`](crate::model::DeviceTree::from_fdt)
+    /// first. [`DeviceTree`](crate::model::DeviceTree) stores the nodes in a
+    /// hash map for constant-time lookup.
     ///
     /// # Examples
     ///

src/fdt/node.rs

@@ -105,7 +105,11 @@ impl<'a> FdtNode<'a> {
     /// # Performance
     ///
     /// This method's performance is linear in the number of children of this
-    /// node because it iterates through the children.
+    /// node because it iterates through the children. If you need to call this
+    /// often, consider converting to a
+    /// [`DeviceTreeNode`](crate::model::DeviceTreeNode) first. Child lookup
+    /// on a [`DeviceTreeNode`](crate::model::DeviceTreeNode) is a
+    /// constant-time operation.
     ///
     /// # Errors
     ///

src/lib.rs

@@ -23,6 +23,11 @@
 #![warn(missing_docs, rustdoc::missing_crate_level_docs)]
 #![cfg_attr(docsrs, feature(doc_cfg))]
 
+#[cfg(feature = "alloc")]
+extern crate alloc;
+
 pub mod error;
 pub mod fdt;
 pub mod memreserve;
+#[cfg(feature = "write")]
+pub mod model;

src/model/mod.rs

@@ -0,0 +1,132 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! A read-write, in-memory representation of a device tree.
+//!
+//! This module provides the [`DeviceTree`], [`DeviceTreeNode`], and
+//! [`DeviceTreeProperty`] structs, which can be used to create or modify a
+//! device tree in memory. The [`DeviceTree`] can then be serialized to a
+//! flattened device tree blob.
+
+use alloc::vec::Vec;
+
+use crate::error::FdtError;
+use crate::fdt::Fdt;
+use crate::memreserve::MemoryReservation;
+mod node;
+mod property;
+pub use node::{DeviceTreeNode, DeviceTreeNodeBuilder};
+pub use property::DeviceTreeProperty;
+
+/// A mutable, in-memory representation of a device tree.
+///
+/// This struct provides a high-level API for creating and modifying a device
+/// tree. It can be created from scratch or by parsing an existing FDT blob.
+///
+/// # Examples
+///
+/// ```
+/// # use dtoolkit::model::{DeviceTree, DeviceTreeNode};
+/// let root = DeviceTreeNode::new("/");
+/// let mut tree = DeviceTree::new(root);
+/// tree.root_mut().add_child(DeviceTreeNode::new("child"));
+/// let child = tree.find_node_mut("/child").unwrap();
+/// ```
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DeviceTree {
+    pub(self) root: DeviceTreeNode,
+    /// The memory reservations for this device tree.
+    pub memory_reservations: Vec<MemoryReservation>,
+}
+
+impl DeviceTree {
+    /// Creates a new `DeviceTree` with the given root node.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use dtoolkit::model::{DeviceTree, DeviceTreeNode};
+    /// let root = DeviceTreeNode::new("/");
+    /// let tree = DeviceTree::new(root);
+    /// ```
+    #[must_use]
+    pub fn new(root: DeviceTreeNode) -> Self {
+        Self {
+            root,
+            memory_reservations: Vec::new(),
+        }
+    }
+
+    /// Creates a new `DeviceTree` from a `Fdt`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use dtoolkit::{fdt::Fdt, model::DeviceTree};
+    /// # let dtb = include_bytes!("../../tests/dtb/test.dtb");
+    /// let fdt = Fdt::new(dtb).unwrap();
+    /// let tree = DeviceTree::from_fdt(&fdt).unwrap();
+    /// ```
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the root node of the `Fdt` cannot be parsed.
+    pub fn from_fdt(fdt: &Fdt<'_>) -> Result<Self, FdtError> {
+        let root = DeviceTreeNode::try_from(fdt.root()?)?;
+        let memory_reservations: Result<Vec<_>, _> = fdt.memory_reservations().collect();
+        Ok(DeviceTree {
+            root,
+            memory_reservations: memory_reservations?,
+        })
+    }
+
+    /// Returns a reference to the root node of the device tree.
+    #[must_use]
+    pub fn root(&self) -> &DeviceTreeNode {
+        &self.root
+    }
+
+    /// Returns a mutable reference to the root node of the device tree.
+    pub fn root_mut(&mut self) -> &mut DeviceTreeNode {
+        &mut self.root
+    }
+
+    /// Finds a node by its path and returns a mutable reference to it.
+    ///
+    /// # Performance
+    ///
+    /// This method traverses the device tree, but since child lookup is a
+    /// constant-time operation, performance is linear in the number of path
+    /// segments.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use dtoolkit::model::{DeviceTree, DeviceTreeNode};
+    /// let mut tree = DeviceTree::new(DeviceTreeNode::new("/"));
+    /// tree.root_mut().add_child(DeviceTreeNode::new("child"));
+    /// let child = tree.find_node_mut("/child").unwrap();
+    /// assert_eq!(child.name(), "child");
+    /// ```
+    pub fn find_node_mut(&mut self, path: &str) -> Option<&mut DeviceTreeNode> {
+        if !path.starts_with('/') {
+            return None;
+        }
+        let mut current_node = &mut self.root;
+        if path == "/" {
+            return Some(current_node);
+        }
+        for component in path.split('/').filter(|s| !s.is_empty()) {
+            match current_node.child_mut(component) {
+                Some(node) => current_node = node,
+                None => return None,
+            }
+        }
+        Some(current_node)
+    }
+}