Struct fdt_rs::DevTree

pub struct DevTree<'a> { /* fields omitted */ }

A parseable Flattened Device Tree.

This parser was written according to the v0.3 specification provided at https://www.devicetree.org/

Implementations

impl<'a> DevTree<'a>

pub const MIN_HEADER_SIZE: usize

pub unsafe fn verify_magic(buf: &[u8]) -> Result<(), DevTreeError>

Verify the magic header of a Device Tree buffer

Safety

Callers of this method the must guarantee the following:

• The passed buffer is 32-bit aligned.

The passed byte buffer will be interpreted as a Flattened Device Tree. For this reason this API is marked unsafe.

pub unsafe fn read_totalsize(buf: &[u8]) -> Result<usize, DevTreeError>

Using the provided byte slice this method will:

1. Verify that the slice begins with the magic Device Tree header
2. Return the reported totalsize field of the Device Tree header

When one must parse a Flattened Device Tree, it's possible that the actual size of the device tree may be unknown. For that reason, this method can be called before constructing the DevTree.

Once known, the user should resize the raw byte slice to this function's return value and pass that slice to DevTree::new().

Example

// Data is re-interpreted as a device tree, this is unsafe.
// See safety section
unsafe {
    let size = DevTree::read_totalsize(buf)?;
    let buf = &buf[..size];
    let dt = DevTree::new(buf)?;
}

Safety

Callers of this method the must guarantee the following:

• The passed buffer is 32-bit aligned.
• The passed buffer is of at least DevTree::MIN_HEADER_SIZE bytes in length

The passed byte buffer will be interpreted as a Flattened Device Tree. For this reason this API is marked unsafe.

pub unsafe fn new(buf: &'a [u8]) -> Result<Self, DevTreeError>

Construct the parseable DevTree object from the provided byte slice.

Safety

Callers of this method the must guarantee the following:

• The passed buffer is 32-bit aligned.
• The passed buffer is exactly the length returned by Self::read_totalsize()

#[must_use]pub fn totalsize(&self) -> usize

Returns the totalsize field of the Device Tree

#[must_use]pub fn off_mem_rsvmap(&self) -> usize

Returns the of rsvmap offset field of the Device Tree

#[must_use]pub fn off_dt_struct(&self) -> usize

Returns the of dt_struct offset field of the Device Tree

#[must_use]pub fn off_dt_strings(&self) -> usize

Returns the of dt_strings offset field of the Device Tree

#[must_use]pub fn reserved_entries(&self) -> DevTreeReserveEntryIter

Returns an iterator over the Dev Tree "5.3 Memory Reservation Blocks"

#[must_use]pub fn nodes(&self) -> DevTreeNodeIter

Returns an iterator over DevTreeNode objects

#[must_use]pub fn items(&self) -> DevTreeIter

Returns an iterator over objects within the DevTreeItem enum

pub fn root(&self) -> Option<DevTreeNode>

Returns the root DevTreeNode object of the device tree (if it exists).

pub fn find<F>(
    &'a self,
    predicate: F
) -> Option<(DevTreeItem<'a>, DevTreeIter<'a>)> where
    F: Fn(&DevTreeItem) -> Result<bool, DevTreeError>, 

Map the supplied predicate over the DevTreeItem enum.

If the predicate returns true, Some((DevTreeItem, iters::DevTreeIter)) will be returned. The iters::DevTreeIter may be used to continue searching through the tree.

The predicate function may return true to simply terminate the search.

Example

fn is_uart_compatible(item: &DevTreeItem) -> Result<bool, DevTreeError> {
    unsafe {
        match item {
            DevTreeItem::Prop(p) => {
                Ok((p.name()? == "compatible") && (p.get_str()? == "ns16550a"))
            },
            _ => Ok(false),
        }
    }
}

// Print the names of all compatible uarts
if let Some((DevTreeItem::Prop(compatible_prop), mut iter)) = devtree.find(is_uart_compatible) {
    println!("{}", compatible_prop.parent().name()?);

    // Continue the search and keep printing their names.
    while let Some((DevTreeItem::Prop(compatible_prop), mut iter)) = iter.find(is_uart_compatible) {
        println!("{}", compatible_prop.parent().name()?);
    }
}

pub fn find_prop<F>(
    &'a self,
    predicate: F
) -> Option<(DevTreeProp<'a>, DevTreePropIter<'a>)> where
    F: Fn(&DevTreeProp) -> Result<bool, DevTreeError>, 

Map the supplied predicate over all DevTreeProp objects

If the predicate returns true, Some((DevTreeProp, iters::DevTreePropIter)) will be returned. The iters::DevTreePropIter may be used to continue searching through the tree.

Example

// Print the first "ns16550a" compatible node.
if let Some((compatible_prop, _)) = devtree.find_prop(|prop| unsafe {
    Ok((prop.name()? == "compatible") && (prop.get_str()? == "ns16550a"))
    }) {
    println!("{}", compatible_prop.parent().name()?);
}

pub fn find_node<F>(
    &'a self,
    predicate: F
) -> Option<(DevTreeNode<'a>, DevTreeNodeIter<'a>)> where
    F: Fn(&DevTreeNode) -> Result<bool, DevTreeError>, 

Map the supplied predicate over all DevTreeNode objects

If the predicate returns true, Some((DevTreeItem, iters::DevTreeNodeIter)) will be returned. The iters::DevTreeNodeIter may be used to continue searching through the tree.

pub fn find_first_compatible_node(
    &'a self,
    string: &Str
) -> Option<DevTreeNode<'a>>

Returns the first DevTreeNode object with the provided compatible device tree property or None if none exists.

Trait Implementations

impl<'a> Clone for DevTree<'a>

fn clone(&self) -> DevTree<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Copy for DevTree<'a>

impl<'a> Debug for DevTree<'a>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.