dtlib

This is the low-level DTS parser.

A library for extracting information from .dts (devicetree) files. See the documentation for the DT and Node classes for more information.

The top-level entry point of the library is the DT class. DT.__init__() takes a .dts file to parse and a list of directories to search for any /include/d files.

class devicetree.dtlib.DT(filename: str, include_path: Iterable[str] = (), force: bool = False)

Represents a devicetree parsed from a .dts file (or from many files, if the .dts file /include/s other files). Creating many instances of this class is fine. The library has no global state.

These attributes are available on DT instances:

root:

A Node instance representing the root (/) node.

alias2node:

A dictionary that maps maps alias strings (from /aliases) to Node instances

label2node:

A dictionary that maps each node label (a string) to the Node instance for the node.

label2prop:

A dictionary that maps each property label (a string) to a Property instance.

label2prop_offset:

A dictionary that maps each label (a string) within a property value (e.g., ‘x = label_1: < 1 label2: 2 >;’) to a (prop, offset) tuple, where ‘prop’ is a Property instance and ‘offset’ the byte offset (0 for label_1 and 4 for label_2 in the example).

phandle2node:

A dictionary that maps each phandle (a number) to a Node instance.

memreserves:

A list of (labels, address, length) tuples for the /memreserve/s in the .dts file, in the same order as they appear in the file.

‘labels’ is a possibly empty set with all labels preceding the memreserve (e.g., ‘label1: label2: /memreserve/ …’). ‘address’ and ‘length’ are numbers.

filename:

The filename passed to the DT constructor.

__init__(filename: str, include_path: Iterable[str] = (), force: bool = False)

Parses a DTS file to create a DT instance. Raises OSError if ‘filename’ can’t be opened, and DTError for any parse errors.

filename:: Path to the .dts file to parse.
include_path:: An iterable (e.g. list or tuple) containing paths to search for /include/d and /incbin/’d files. By default, files are only looked up relative to the .dts file that contains the /include/ or /incbin/.
force:: Try not to raise DTError even if the input tree has errors. For experimental use; results not guaranteed.

get_node(path: str) → devicetree.dtlib.Node

Returns the Node instance for the node with path or alias ‘path’ (a string). Raises DTError if the path or alias doesn’t exist.

For example, both dt.get_node(“/foo/bar”) and dt.get_node(“bar-alias”) will return the ‘bar’ node below:

/dts-v1/;

/ {

foo {

bar_label: bar {
baz { };

};

};

aliases {
bar-alias = &bar-label;

};

};

Fetching subnodes via aliases is supported: dt.get_node(“bar-alias/baz”) returns the ‘baz’ node.

has_node(path: str) → bool: Returns True if the path or alias ‘path’ exists. See Node.get_node().

node_iter() → Iterable[devicetree.dtlib.Node]

Returns a generator for iterating over all nodes in the devicetree.

For example, this will print the name of each node that has a property called ‘foo’:

for node in dt.node_iter():

if “foo” in node.props:
print(node.name)

property root: devicetree.dtlib.Node: See the class documentation.

class devicetree.dtlib.Node(name: str, parent: Optional[devicetree.dtlib.Node], dt: devicetree.dtlib.DT)

Represents a node in the devicetree (‘node-name { … };’).

These attributes are available on Node instances:

name:

The name of the node (a string).

unit_addr:

The portion after the ‘@’ in the node’s name, or the empty string if the name has no ‘@’ in it.

Note that this is a string. Run int(node.unit_addr, 16) to get an integer.

props:

A collections.OrderedDict that maps the properties defined on the node to their values. ‘props’ is indexed by property name (a string), and values are Property objects.

To convert property values to Python numbers or strings, use dtlib.to_num(), dtlib.to_nums(), or dtlib.to_string().

Property values are represented as ‘bytes’ arrays to support the full generality of DTS, which allows assignments like

x = “foo”, < 0x12345678 >, [ 9A ];

This gives x the value b”foo0x12x34x56x78x9A”. Numbers in DTS are stored in big-endian format.

nodes:

A collections.OrderedDict containing the subnodes of the node, indexed by name.

labels:

A list with all labels pointing to the node, in the same order as the labels appear, but with duplicates removed.

‘label_1: label_2: node { … };’ gives ‘labels’ the value [“label_1”, “label_2”].

parent:

The parent Node of the node. ‘None’ for the root node.

path:

The path to the node as a string, e.g. “/foo/bar”.

dt:

The DT instance this node belongs to.

class devicetree.dtlib.Property(node: devicetree.dtlib.Node, name: str)

Represents a property (‘x = …’).

These attributes are available on Property instances:

name:

The name of the property (a string).

value:

The value of the property, as a ‘bytes’ string. Numbers are stored in big-endian format, and strings are null-terminated. Putting multiple comma-separated values in an assignment (e.g., ‘x = < 1 >, “foo”’) will concatenate the values.

See the to_*() methods for converting the value to other types.

type:

The type of the property, inferred from the syntax used in the assignment. This is one of the following constants (with example assignments):

Assignment | Property.type —————————-+———————— foo; | dtlib.Type.EMPTY foo = []; | dtlib.Type.BYTES foo = [01 02]; | dtlib.Type.BYTES foo = /bits/ 8 <1>; | dtlib.Type.BYTES foo = <1>; | dtlib.Type.NUM foo = <>; | dtlib.Type.NUMS foo = <1 2 3>; | dtlib.Type.NUMS foo = <1 2>, <3>; | dtlib.Type.NUMS foo = “foo”; | dtlib.Type.STRING foo = “foo”, “bar”; | dtlib.Type.STRINGS foo = <&l>; | dtlib.Type.PHANDLE foo = <&l1 &l2 &l3>; | dtlib.Type.PHANDLES foo = <&l1 &l2>, <&l3>; | dtlib.Type.PHANDLES foo = <&l1 1 2 &l2 3 4>; | dtlib.Type.PHANDLES_AND_NUMS foo = <&l1 1 2>, <&l2 3 4>; | dtlib.Type.PHANDLES_AND_NUMS foo = &l; | dtlib.Type.PATH Anything else | dtlib.Type.COMPOUND

Anything else includes properties mixing phandle (<&label>) and node path (&label) references with other data.

Data labels in the property value do not influence the type.

labels:

A list with all labels pointing to the property, in the same order as the labels appear, but with duplicates removed.

‘label_1: label2: x = …’ gives ‘labels’ the value {“label_1”, “label_2”}.

offset_labels:

A dictionary that maps any labels within the property’s value to their offset, in bytes. For example, ‘x = < 0 label_1: 1 label_2: >’ gives ‘offset_labels’ the value {“label_1”: 4, “label_2”: 8}.

Iteration order will match the order of the labels on Python versions that preserve dict insertion order.

node:

The Node the property is on.

class devicetree.dtlib.DTError: Exception raised for devicetree-related errors