Skip to main content

Crate dtoolkit

Crate dtoolkit 

Source
Expand description

A library for parsing and manipulating Flattened Device Tree (FDT) blobs.

This library provides a comprehensive API for working with FDTs, including:

  • An in-place API for parsing, traversing, and modifying FDTs without memory allocation.
  • An intermediate representation API for creating and modifying FDTs using computationally efficient data structures.
  • Support for applying device tree overlays.
  • Outputting device trees in DTS source format.

The library is written purely in Rust and is #![no_std] compatible. If you don’t need the Device Tree manipulation functionality, the library is also no-alloc-compatible.

§In-place API

The in-place API is centered around the Fdt struct for read-only operations, and the FdtMut struct for mutable operations. Both provide a safe, zero-copy view of an FDT blob. You can use this API to traverse the device tree, inspect nodes and properties, and read or write property values in-place.

Note that because these structs operate directly on the serialized format, certain operations such as node or property lookups run in linear time. If you need to perform these operations often, and you can spare extra memory, it might be beneficial to convert from Fdt to DeviceTree first.

§Intermediate Representation API

The intermediate representation API is centered around the DeviceTree struct, which provides a mutable representation of a device tree built upon computationally efficient data structures. You can use this API to create new device trees from scratch, modify existing ones, and serialize them back to an FDT blob.

Internally it is built upon hash maps, meaning that most lookup and modification operations run in constant time.

§Examples

§General usage with the Intermediate Representation API

use dtoolkit::fdt::Fdt;
use dtoolkit::model::{DeviceTree, DeviceTreeNode, DeviceTreeProperty};
use dtoolkit::{Node, Property};

// Create a new device tree from scratch.
let mut tree = DeviceTree::new();

// Add a child node to the root.
let child = DeviceTreeNode::builder("child")
    .unwrap()
    .property(DeviceTreeProperty::new("my-property", "hello").unwrap())
    .build();
tree.root.add_child(child);

// Serialize the device tree to a DTB.
let dtb = tree.to_dtb();

// Parse the DTB with the read-only API.
let fdt = Fdt::new(&dtb).unwrap();

// Find the child node and read its property.
let child_node = fdt.find_node("/child").unwrap();
let prop = child_node.property("my-property").unwrap();
let val = prop.value_as::<&str>().unwrap();
assert_eq!(val, "hello");

// Display the DTS
println!("{}", fdt);

§In-place editing API

use dtoolkit::fdt_mut::FdtMut;
use dtoolkit::{Node, Property};

let mut fdt = FdtMut::from_slice(&mut dtb).unwrap();

let mut node = fdt.find_node_mut("/test-props").unwrap();
node.property_mut("str-prop")
    .unwrap()
    .set_value(b"hello rust\0");
let is_removed = node.remove_property("u32-prop");

§Applying Device Tree Overlays

use dtoolkit::fdt::Fdt;
use dtoolkit::model::DeviceTree;
use dtoolkit::model::overlay::OverlayApplier;

let mut base = DeviceTree::from_fdt(&Fdt::new(base_dtb).unwrap());
let overlay = Fdt::new(overlay_dtb).unwrap();

let mut applier = OverlayApplier::new(&mut base);
applier.apply_overlay(&overlay).unwrap();

Modules§

error
Error types for the dtoolkit crate.
fdt
A read-only API for parsing and traversing a Flattened Device Tree (FDT).
fdt_mut
A read-write API for modifying a Flattened Device Tree (FDT) in-place.
memreserve
Device tree memory reservations.
modelwrite
A read-write, in-memory representation of a device tree.
overlayoverlay
Helper types and methods for inspecting Device Tree Overlays (DTBOs).
standard
Standard nodes and properties.

Structs§

Cells
An integer value split into several big-endian u32 parts.
FdtStringListIterator
An iterator over the strings in a device tree property.
PropEncodedArrayIterator
An iterator over the prop-encoded-array elements of a device tree property.

Traits§

FromPropertyValue
A trait for types that can be parsed from a device tree property value.
Node
A device tree node.
Property
A property of a device tree node.
ToPropertyValue
A trait for types that can be serialized into a device tree property value.