Pkg.FDT — API for parsing Flattened Device Tree blobs

Overview

The Pkg.FDT module contains the API for parsing Flattened Device Tree (FDT / DTB) blobs. DTBs are produced by the Devicetree Compiler (dtc) and consumed by bootloaders and the Linux kernel to describe non-discoverable hardware: CPUs, memory regions, peripherals, interrupt controllers, clocks, pin configurations and so on. They are also used as device tree overlays (.dtbo) to patch a base tree at boot time. The parser supports DTB versions 1 through 17, which covers every blob produced by mainline dtc and the Linux kernel.

Inspecting a Device Tree Blob

The following code example demonstrates how to load a DTB, inspect its header, walk the root node and dump the tree as textual DTS source:

from Pro.Core import *
from Pkg.FDT import *

def inspectDTB(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = FDTObject()
    if not obj.Load(c) or not obj.Initialize():
        return
    print("version:", obj.GetVersion(), "size:", obj.GetTotalSize())
    for addr, size in obj.GetMemoryReservations():
        print("  reserve 0x%x size 0x%x" % (addr, size))
    root = obj.GetRootNode()
    if root is not None:
        model = root.GetProperty("model")
        if model:
            print("model:", model.data.rstrip(b"\x00").decode("utf-8", "replace"))
        cpus = obj.FindNode("/cpus")
        if cpus is not None:
            print("cpu nodes:", len(cpus.children))
    print(obj.DumpDTS())

Module API

Pkg.FDT module API.

Classes:

FDTEntry()	Describes a single region inside a Flattened Device Tree blob.
FDTNode()	Represents a node in the device tree.
FDTObject()	This class represents a Flattened Device Tree (FDT / DTB) blob.
FDTProperty()	Represents a single property attached to a node in the device tree.

class FDTEntry

Describes a single region inside a Flattened Device Tree blob.

Each entry records the offset, the size, and a descriptive name of a logical region of the file: the header, the memory reservation block, the structure block, and the strings block. Use FDTObject.GetEntries() to enumerate all entries.

class FDTNode

Represents a node in the device tree.

A node has a name (e.g. "cpu@0"), an ordered list of properties, and an ordered list of child nodes. The root node returned by FDTObject.GetRootNode() has an empty name in the FDT spec but is rendered as / when dumped to DTS.

The id field is a stable walk-order index assigned during parsing and used by the UI tree-view callback. The offset and size fields cover the byte range of the node (from its FDT_BEGIN_NODE token through the matching FDT_END_NODE token, inclusive) inside the structure block of the blob.

Methods:

GetChild(name)	Returns the immediate child node with the given name, or None if no such child exists.
GetDetails()	Returns a human-readable summary of the node, including its offset, size, child count and a DTS-style listing of every property.
GetLabel()	Returns the display label for the node.
GetProperty(name)	Returns the property with the given name, or None if no such property exists on this node.

GetChild(name: str) → Optional[Pkg.FDT.FDTNode]

Returns the immediate child node with the given name, or None if no such child exists.

Parameters

name (str) – The child node name to look up (e.g. "cpus").

Returns

Returns the matching child node if found; otherwise returns None.

Return type

Optional[FDTNode]

GetDetails() → str

Returns a human-readable summary of the node, including its offset, size, child count and a DTS-style listing of every property.

Returns

Returns the formatted summary text.

Return type

str

GetLabel() → str

Returns the display label for the node.

Returns "/" for the root node and the node name otherwise.

Returns

Returns the node label.

Return type

str

GetProperty(name: str) → Optional[Pkg.FDT.FDTProperty]

Returns the property with the given name, or None if no such property exists on this node.

Parameters

name (str) – The property name to look up.

Returns

Returns the matching property if found; otherwise returns None.

Return type

Optional[FDTProperty]

class FDTObject

Bases: Pro.Core.CFFObject

This class represents a Flattened Device Tree (FDT / DTB) blob.

Device Tree Blobs are produced by the Devicetree Compiler (dtc) and consumed by bootloaders and the Linux kernel to describe non-discoverable hardware. A blob is composed of a header, a memory reservation block, a structure block and a strings block. This class parses all four sections, exposes the resulting node tree through GetRootNode() / FindNode(), and can render the tree back as a textual DTS source via DumpDTS().

The parser supports DTB versions 1 through 17 (last compatible version 16), which covers every blob produced by mainline dtc and the Linux kernel.

Methods:

BuildNodeMap(*[, wo])	Returns a flat map from node id to a (node, parent_id, row_in_parent) tuple.
DumpDTS(*[, wo])	Renders the parsed tree as a textual DTS source.
FindNode(path)	Returns the node at the given absolute path, or None if the path does not resolve.
GetBootCpuId()	Returns the physical ID of the boot CPU, as recorded in the header.
GetEntries()	Returns the list of logical entries discovered in the blob.
GetLastCompatibleVersion()	Returns the oldest format version with which the blob is backward compatible.
GetMemoryReservations()	Returns the list of (address, size) pairs declared in the memory reservation block.
GetRootNode()	Returns the root node of the parsed device tree.
GetTotalSize()	Returns the total size of the blob in bytes, as recorded in the header.
GetVersion()	Returns the DTB format version recorded in the header.

BuildNodeMap(*, wo: Optional[Any] = None) → dict

Returns a flat map from node id to a (node, parent_id, row_in_parent) tuple.

The root node maps to (root, 0, 0). This map is consumed by the UI tree-view callback to navigate the device tree by id.

Parameters

wo (Optional[Any]) – Optional wait object for abort support on very large trees.

Returns

Returns the id-keyed node map.

Return type

dict

DumpDTS(*, wo: Optional[Any] = None) → str

Renders the parsed tree as a textual DTS source.

The output uses heuristics on property names to format values as string lists, cell arrays or raw byte arrays. The resulting text is meant for human inspection and is not guaranteed to round-trip through the Devicetree Compiler.

Parameters

wo (Optional[Any]) – Optional wait object for abort support on very large trees.

Returns

Returns the DTS-formatted text.

Return type

str

FindNode(path: str) → Optional[Pkg.FDT.FDTNode]

Returns the node at the given absolute path, or None if the path does not resolve.

Paths use / as separator and start with a leading slash, e.g. "/cpus/cpu@0". Passing "/" (or an empty string) returns the root node.

Parameters

path (str) – The absolute node path.

Returns

Returns the matching node if found; otherwise returns None.

Return type

Optional[FDTNode]

GetBootCpuId() → int

Returns the physical ID of the boot CPU, as recorded in the header.

Only meaningful for DTB version 2 or later; returns 0 otherwise.

Returns

Returns the boot CPU physical ID.

Return type

int

GetEntries() → List[Pkg.FDT.FDTEntry]

Returns the list of logical entries discovered in the blob.

Entries cover the header, the memory reservation block, the structure block and the strings block.

Returns

Returns the list of entries.

Return type

List[FDTEntry]

GetLastCompatibleVersion() → int

Returns the oldest format version with which the blob is backward compatible.

Returns

Returns the last compatible version (typically 16).

Return type

int

GetMemoryReservations() → List[Tuple[int, int]]

Returns the list of (address, size) pairs declared in the memory reservation block.

These regions describe physical memory areas that the operating system must not overwrite (e.g. firmware or DMA-reserved memory).

Returns

Returns the list of reservation tuples; the list is empty when no reservations are present.

Return type

List[Tuple[int, int]]

GetRootNode() → Optional[Pkg.FDT.FDTNode]

Returns the root node of the parsed device tree.

The root node has an empty name in the FDT spec; when rendered as DTS it is shown as /.

Returns

Returns the root node if parsing succeeded; otherwise returns None.

Return type

Optional[FDTNode]

GetTotalSize() → int

Returns the total size of the blob in bytes, as recorded in the header.

Returns

Returns the blob size.

Return type

int

GetVersion() → int

Returns the DTB format version recorded in the header.

Returns

Returns the format version (typically 17).

Return type

int

class FDTProperty

Represents a single property attached to a node in the device tree.

A property is a name/value pair where the value is an opaque byte string. The actual interpretation of the bytes depends on the property name and is described by the Devicetree Specification (e.g. compatible is a list of NUL-separated strings, reg is a sequence of big-endian 32-bit cells).