edtsdb API

edtsdb is a Python module with the primary class: EDTSDb.

The basis for the edtsb module is the edtlib library.

EDTSDb

cogeno::modules::edtsdb::consumer::EDTSConsumerMixin.device_id_by_name(self, name)

Get device id of activated device with given name.

Return

device id

Parameters

• name:

cogeno.modules.edtsdb.database.EDTSDb : public cogeno.modules.edtsdb.consumer.EDTSConsumerMixin , public cogeno.modules.edtsdb.provider.EDTSProviderMixin , public cogeno.modules.edtsdb.extractor.EDTSExtractorMixin , public Mapping

Extended DTS database.

Database schema:

_edts dict(
  'aliases': dict(alias) : sorted list(device-id)),
  'chosen': dict(chosen),
  'devices':  dict(device-id :  device-struct),
  'compatibles':  dict(compatible : sorted list(device-id)),
  ...
)

device-struct dict(
  'device-id' : device-id,
  'compatible' : list(compatible) or compatible,
  'label' : label,
  '<property-name>' : property-value
)

property-value
  for "boolean", "string", "int" -> string
  for 'array', "string-array", "uint8-array" -> dict(index : string)
  for "phandle-array" -> dict(index : device-id)

Database types:

• device-id: opaque id for a device (do not use for other purposes),

• compatible: any of [‘st,stm32-spi-fifo’, …] - ‘compatibe’ from <binding>.yaml

• label: any of [‘UART_0’, ‘SPI_11’, …] - label directive from DTS

Subclassed by cogeno.modules.edts.EDTSDatabase

Public Functions

__init__(self, args, kw)

__getitem__(self, key)

__iter__(self)

__len__(self)

The EDTSDb class includes (sub-classes) several mixin classes:

cogeno.modules.edtsdb.consumer.EDTSConsumerMixin : public object

ETDS Database consumer.

Methods for ETDS database usage.

Subclassed by cogeno.modules.edtsdb.database.EDTSDb

Public Functions

info(self)

Get info.

Return

edts ‘info’ dict

Parameters

• None:

compatibles(self)

Get compatibles.

Return

edts ‘compatibles’ dict

Parameters

• None:

aliases(self)

Get aliases.

Return

edts ‘aliases’ dict

Parameters

• None:

chosen(self)

Get chosen.

Return

edts ‘chosen’ dict

Parameters

• None:

device_ids_by_compatible(self, compatibles)

Get device ids of all activated compatible devices.

Return

list of device ids of activated devices that are compatible

Parameters

• compatibles: compatible(s)

device_ids_by_dependency_order(self)

Get device ids of activated devices sorted by dependency ordinal.

Device ids of devices that are not activated but have an ordinal associated are set to None.

Return

list of device ids of activated devices sorted by dependency ordinal

Parameters

• None:

device_id_by_name(self, name)

Get device id of activated device with given name.

Return

device id

Parameters

• name:

device_id_by_alias(self, alias)

Get device id of activated device for given alias.

Return

device id or None

Parameters

• alias:

device_id_by_chosen(self, chosen)

Get device id of activated device for given chosen.

Return

device id or None

Parameters

• chosen:

device_name_by_id(self, device_id)

Get label/ name of a device by device id.

If the label is omitted, the name is taken from the node name (including unit address).

Return

name

Parameters

• device_id:

device_property(self, device_id, property_path, default='<unset>')

Get device tree property value of a device.

Return

property value

Parameters

• device_id:

• property_path: Path of the property to access (e.g. ‘reg/0/address’, ‘interrupts/prio’, ‘device_id’, …)

• default: Default value provided if device or property not available

device_properties(self, device_id)

Get all device tree properties of a device.

Return

Dictionary of properties

Parameters

• device_id:

device_properties_flattened(self, device_id, path_prefix='')

Device properties flattened to property path : value.

Return

dictionary of property_path and property_value

Parameters

• device_id:

• path_prefix:

device_template_substitute(self, device_id, template, presets={}, aliases={})

Substitude device property value placeholders in template.

Local placeholders may be defined with direct and indirect path resolution:

• ${<property_path>}

• ${path/${<property_path>}}

• ${path/${<device-id>:<property_path>}}

Global placeholders may also be defined with direct and indirect path resolution:

• ${<device-id>:<property_path>}

• ${${<property_path>}:<property_path>}

• ${${path/${<property_path>}}:<property_path>}

• ${${path/${<device-id>:<property_path>}}:<property_path>}

• ${${<device-id>:<property_path>}:<property_path>}

• ${${<device-id>:path/${<property_path>}}:<property_path>}

• ${${<device-id>:path/${<device-id>:<property_path>}}:<property_path>}

Parameters

• device_id:

• template:

• presets: dict of preset property-path : property value items either of the local form “<property_path>” : value or the global form “<device-id>:<property_path>” : value

• aliases: dict of property path alias : property path items.

load(self, file_path)

Load extended device tree database from JSON file.

Parameters

• file_path: Path of JSON file

_DeviceGlobalTemplate : public Template

Public Static Attributes

idpattern = r'/[_a-z0-9\-/,@:]*'

_DeviceLocalTemplate : public Template

Public Static Attributes

idpattern = r'[_a-z][_a-z0-9\-/,]*'

cogeno.modules.edtsdb.extractor.EDTSExtractorMixin : public object

ETDS Database extractor.

Methods for ETDS database extraction from DTS.

Subclassed by cogeno.modules.edtsdb.database.EDTSDb

Public Functions

extract(self, dts_path, bindings_dirs, bindings_exclude, bindings_no_default)

Extract DTS info to database.

Parameters

• dts_path: DTS file

• bindings_dirs: YAML file directories, we allow multiple

• bindings_exclude: YAML file directories and YAML files, we allow multiple

• bindings_no_default: Do not use default bindings

dts_path(self)

Device tree file path.

Return

Device tree file path

bindings_dirs(self)

Bindings directories paths.

Return

List of binding directories

dts_source(self)

DTS source code.

DTS source code of the loaded devicetree after merging nodes and processing /delete-node/ and /delete-property/.

Return

DTS source code as string

cogeno.modules.edtsdb.provider.EDTSProviderMixin : public object

ETDS Database provider.

Methods for ETDS database creation.

Subclassed by cogeno.modules.edtsdb.database.EDTSDb

Public Functions

insert_alias(self, alias_path, alias_value)

Insert an alias.

Parameters

• alias_path: Alias

• alias_value: The value the alias aliases.

insert_chosen(self, chosen_path, chosen_value)

insert_child_property(self, device_id, child_name, property_path, property_value)

Insert property value for the child of a device id.

Parameters

• device_id:

• child_name:

• property_path: Path of the property to access (e.g. ‘reg/0’, ‘interrupts/prio’, ‘label’, …)

• property_value: value

insert_device_property(self, device_id, property_path, property_value)

Insert property value for the device of the given device id.

Parameters

• device_id:

• property_path: Path of the property to access (e.g. ‘reg/0’, ‘interrupts/prio’, ‘label’, …)

• property_value: value

save(self, file_path)

Write json file.

Parameters

• file_path: Path of the file to write

edtlib

class cogeno.modules.edtsdb.libraries.edtlib.EDT

Represents a devicetree augmented with information from bindings.

These attributes are available on EDT objects:

nodes:
  A list of Node objects for the nodes that appear in the devicetree

compat2nodes:
  A collections.defaultdict that maps each 'compatible' string that appears
  on some Node to a list of Nodes with that compatible.

compat2okay:
  Like compat2nodes, but just for nodes with status 'okay'.

  For example, edt.compat2okay["bar"] would include the 'foo' and 'bar'
  nodes below.

    foo {
            compatible = "bar";
            status = "okay";
            ...
    };
    bar {
            compatible = "foo", "bar", "baz";
            status = "okay";
            ...
    }

label2node:
  A collections.OrderedDict that maps a node label to the node with
  that label.

chosen_nodes:
  A collections.OrderedDict that maps the properties defined on the
  devicetree's /chosen node to their values. 'chosen' is indexed by
  property name (a string), and values are converted to Node objects.
  Note that properties of the /chosen node which can't be converted
  to a Node are not included in the value.

dts_path:
  The .dts path passed to __init__()

dts_source:
  The final DTS source code of the loaded devicetree after merging nodes
  and processing /delete-node/ and /delete-property/, as a string

bindings_dirs:
  The bindings directory paths passed to __init__()

Public Functions

__init__(self, dts, bindings_dirs, warn_file=None, warn_reg_unit_address_mismatch=True, bindings_exclude=[])

EDT constructor. This is the top-level entry point to the library.

dts:
  Path to devicetree .dts file

bindings_dirs:
  List of paths to directories containing bindings, in YAML format.
  These directories are recursively searched for .yaml files.

warn_file (default: None):
  'file' object to write warnings to. If None, sys.stderr is used.

warn_reg_unit_address_mismatch (default: True):
  If True, a warning is printed if a node has a 'reg' property where
  the address of the first entry does not match the unit address of the
  node

bindings_exclude:
  List of paths to bindings directories and/ or files that shall be excluded
  from usage.

get_node(self, path)

Returns the Node at the DT path or alias 'path'. Raises EDTError if the
path or alias doesn't exist.

chosen_nodes(self)

chosen_node(self, name)

Returns the Node pointed at by the property named 'name' in /chosen, or
None if the property is missing

dts_source(self)

__repr__(self)

scc_order(self)

Returns a list of lists of Nodes where all elements of each list
depend on each other, and the Nodes in any list do not depend
on any Node in a subsequent list.  Each list defines a Strongly
Connected Component (SCC) of the graph.

For an acyclic graph each list will be a singleton.  Cycles
will be represented by lists with multiple nodes.  Cycles are
not expected to be present in devicetree graphs.

Public Members

dts_path

bindings_dirs

nodes

label2node

compat2nodes

compat2okay

class cogeno.modules.edtsdb.libraries.edtlib.Node

Represents a devicetree node, augmented with information from bindings, and
with some interpretation of devicetree properties. There's a one-to-one
correspondence between devicetree nodes and Nodes.

These attributes are available on Node objects:

edt:
  The EDT instance this node is from

name:
  The name of the node

unit_addr:
  An integer with the ...@<unit-address> portion of the node name,
  translated through any 'ranges' properties on parent nodes, or None if
  the node name has no unit-address portion

description:
  The description string from the binding for the node, or None if the node
  has no binding. Leading and trailing whitespace (including newlines) is
  removed.

path:
  The devicetree path of the node

label:
  The text from the 'label' property on the node, or None if the node has
  no 'label'

labels:
  A list of all of the devicetree labels for the node, in the same order
  as the labels appear, but with duplicates removed.
  This corresponds to the actual devicetree source labels, unlike the
  "label" attribute, which is the value of a devicetree property named
  "label".

parent:
  The Node instance for the devicetree parent of the Node, or None if the
  node is the root node

children:
  A dictionary with the Node instances for the devicetree children of the
  node, indexed by name

dep_ordinal:
  A non-negative integer value such that the value for a Node is
  less than the value for all Nodes that depend on it.

  The ordinal is defined for all Nodes including those that are not
  'enabled', and is unique among nodes in its EDT 'nodes' list.

required_by:
  A list with the nodes that directly depend on the node

depends_on:
  A list with the nodes that the node directly depends on

status:
  The node's status property value, as a string, or "okay" if the node
  has no status property set. If the node's status property is "ok",
  it is converted to "okay" for consistency.

read_only:
  True if the node has a 'read-only' property, and False otherwise

matching_compat:
  The 'compatible' string for the binding that matched the node, or None if
  the node has no binding

binding_path:
  The path to the binding file for the node, or None if the node has no
  binding

compats:
  A list of 'compatible' strings for the node, in the same order that
  they're listed in the .dts file

regs:
  A list of Register objects for the node's registers

props:
  A collections.OrderedDict that maps property names to Property objects.
  Property objects are created for all devicetree properties on the node
  that are mentioned in 'properties:' in the binding.

aliases:
  A list of aliases for the node. This is fetched from the /aliases node.

clocks:
  A list of ControllerAndData objects for the clock inputs on the
  node, sorted by index. The list is empty if the node does not have a
  clocks property.

clock_outputs:
  A list of ControllerAndData objects for the clock outputs on the
  node, sorted by index. The list is empty if the node does not have a
  #clock-cells property.

gpio_leds:
  A list of ControllerAndData objects of the leds a gpio leds controller
  controls. The list is empty if the node is not a gpio leds controller or
  it does not have and gpio led children.

interrupts:
  A list of ControllerAndData objects for the interrupts generated by the
  node. The list is empty if the node does not generate interrupts.

pinctrls:
  A list of PinCtrl objects for the pinctrl-<index> properties on the
  node, sorted by index. The list is empty if the node does not have any
  pinctrl-<index> properties.

pinctrl_states:
  A list with the Node instances for the 'pinctrl-state' children of
  a pin controller node. The list is empty if the node does not have any
  pinctrl state children.

pinctrl_gpio_ranges:
  A list of ControllerAndData objects of the gpio ranges a pin controller
  controls. The list is empty if the node is not a pin controller or no
  'gpio-ranges' are defined by the gpio nodes.

pincfgs:
  A list of PinCfg objects for the 'pinctrl-state' node. The list is
  empty if the node is not a 'pinctrl-state' node.

pin_controller:
  The pin controller for the node. Only meaningful for nodes representing
  pinctrl states.

bus:
  If the node is a bus node (has a 'bus:' key in its binding), then this
  attribute holds the bus type, e.g. "i2c" or "spi". If the node is not a
  bus node, then this attribute is None.

on_bus:
  The bus the node appears on, e.g. "i2c" or "spi". The bus is determined
  by searching upwards for a parent node whose binding has a 'bus:' key,
  returning the value of the first 'bus:' key found. If none of the node's
  parents has a 'bus:' key, this attribute is None.

bus_node:
  Like on_bus, but contains the Node for the bus controller, or None if the
  node is not on a bus.

flash_controller:
  The flash controller for the node. Only meaningful for nodes representing
  flash partitions.

partitions:
  A list of Partition objects of the partitions of the 'partitions' node of
  a flash. Only meaningful for nodes representing a flash - otherwise an
  empty list.

spi_cs_gpio:
  The device's SPI GPIO chip select as a ControllerAndData instance, if it
  exists, and None otherwise. See
  Documentation/devicetree/bindings/spi/spi-controller.yaml in the Linux kernel.

Public Functions

name(self)

unit_addr(self)

description(self)

path(self)

label(self)

labels(self)

parent(self)

children(self)

required_by(self)

depends_on(self)

status(self)

read_only(self)

aliases(self)

bus(self)

clocks(self)

on_bus(self)

flash_controller(self)

spi_cs_gpio(self)

__repr__(self)

Public Members

on_bus

compats

matching_compat

binding_path

props

pinctrl_gpio_ranges

clock_outputs

gpio_leds

regs

partitions

name

pinctrl_states

pincfgs

pinctrls

interrupts

class cogeno.modules.edtsdb.libraries.edtlib.Register

Represents a register on a node.

These attributes are available on Register objects:

node:
  The Node instance this register is from

name:
  The name of the register as given in the 'reg-names' property, or None if
  there is no 'reg-names' property

addr:
  The starting address of the register, in the parent address space, or None
  if #address-cells is zero. Any 'ranges' properties are taken into account.

size:
  The length of the register in bytes

Public Functions

__repr__(self)

class cogeno.modules.edtsdb.libraries.edtlib.ControllerAndData

Represents an entry in an 'interrupts' or 'type: phandle-array' property
value, e.g. <&ctrl-1 4 0> in

    cs-gpios = <&ctrl-1 4 0 &ctrl-2 3 4>;

These attributes are available on ControllerAndData objects:

node:
  The Node instance the property appears on

controller:
  The Node instance for the controller (e.g. the controller the interrupt
  gets sent to for interrupts)

data:
  A dictionary that maps names from the *-cells key in the binding for the
  controller to data values, e.g. {"pin": 4, "flags": 0} for the example
  above.

  'interrupts = <1 2>' might give {"irq": 1, "level": 2}.

name:
  The name of the entry as given in
  'interrupt-names'/'gpio-names'/'pwm-names'/etc., or None if there is no
  *-names property

Public Functions

__repr__(self)