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, include_path=())¶

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, include_path=())¶

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/.

get_node(path)¶

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)¶: Returns True if the path or alias ‘path’ exists. See Node.get_node().

node_iter()¶

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)

class devicetree.dtlib.Node(name, parent, 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 represented as ‘bytes’ arrays.

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, name)¶

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