Skip to content

v0.2.4

Latest
Latest
Compare
Choose a tag to compare
@dottspina dottspina released this 09 Dec 07:21
· 1 commit to dtsh-next since this release
v0.2.4
ed7eae7

This release brings a lot of bug fixes and improvements: if you've ever played around with DTSh, and come across some command output that you found suspicious, please try again, and open an issue if things still look weird.

Important

Following Zephyr requirements, the required minimum Python version is now 3.10.

Below is an overview of the most important changes and fixes.

Bindings genealogy

Fixed child-binding depth

DTSh defines the child-binding depth associated to a node as the non negative integer that represents how far we can walk the devicetree backward until the current node is not specified by the child-binding of its parent:

  • 0: this node is not specified by its parent's child-binding
  • 1: child-binding
  • 2: grandchild-binding, etc

The child-binding depth computation assumed that the child-binding: of a parent node, when it exists, is the binding of the child node. This is not always true.

Consider the example bellow:

spi-0 2 3

DTSh 0.2.3 wrongly shows the binding of the node &spi0/lmp90199@0/gpio as a child-binding of the compatible ti,lmp90100:

  • &spi0/lmp90199@0/gpio is not specified by the child-binding of its parent node, but with the compatible string ti,lmp90xxx-gpio
  • only the binding of &spi0/lmp90100@0/channel@0, described as "Channel configuration…", is actually a child-binding

DTSh 0.2.4 fixes the child-binding depth:

spi-0 2 4

But now the binding of &spi0/lmp90100@0/channel@0 appears anchored to the compatible ti,lmp90xxx-gpio, while it's a child-binding of the compatible ti,lmp90100, one more line further up in the list view.
This issue is discussed bellow.

Disabling child-binding anchors by default

Child-binding anchors are produced by the Binding column (C) of formatted tree views.

Things work well when a child-binding immediately follows the binding it's a child of (or even when the same child-binding repeats without confusion):

partitions

But when the parent of a child-binding does not appear immediately above in the list, we don't know how to translate this visually, and anchors are then more confusing than helpful.
This is what happens with the binding of &spi0/lmp90100@0/channel@0 in our initial example.

Child-binding anchors are thus disabled by default, and DTSh would now output:

spi-0 2 4-default

Note: You can still enabled them with the pref.tree.cb_anchor preference.

Find out bindings genealogy

The cat command has been updated to be more helpful with bindings genealogy:

/
> cat -B /soc/iomuxc@30330000/pinctrl/i2c1_default/group0
grandchild-binding of nxp,imx7d-pinctrl

/
> cat -B /soc/iomuxc@30330000/pinctrl/i2c1_default
child-binding of nxp,imx7d-pinctrl

Or more visually visually (with -l):

/
> cat -Bl /soc/iomuxc@30330000/pinctrl/i2c1_default

catBl-node

In the above command output, we see that the node &pinctrl/i2c1_default is specified by a binding without compatible string, with description "iMX pin controller pin group", which is a child-binding of the compatible nxp,imx7d-pinctrl, and itself has a child-binding with description "iMX pin controller pin configuration node".

Properties lineage

When enumerating the properties defined (supported) by a node, DTSh creates hyperlinks to the appropriate YAML specification files. But which are these appropriate files ?

The file answered by the edtlib.PropertySpec.path API, which is always the path of the top-level binding, does not fit our use case:

  • DTSh does not want to tell its users, especially newcomers to Devicetree, that e.g. the wakeup-source property is defined by the "nordic,nrf52-flash-controller" compatible
  • clicking the hyperlink will open nordic,nrf52-flash-controller.yaml, which is useless to learn something about wakeup-source

This is a known issue difficult to address upstream (#5).

Meanwhile, DTSh will implement a workaround, where it retrieves properties lineage a posteriori:

  • starting from the top-level binding, down to the recursively included YAML files, and honoring filters, the first binding file that adds some definition (e.g. required: true) to a property specification, is where the property was modified last: DTSh will by default link properties to these files
  • the file where we find a description for the property is where it was initially specified: this lineage is given by the cat -Bl command

catBl-prop

In the command output above, we read that the property quad-enable-requirements is introduced in jedec,jesd216.yaml, and modified last in nordic,qspi-nor.yaml (to set a default value).

HWMv2 support

DTSh now relies on external CMake cache variables and some heuristic to retrieve the hardware model version used at build-time when the DTS was generated.

The HWM version is determined via simple tricks:

  • if the board target (aka BOARD) contains some /, it's HWMv2
  • assuming we found a valid board directory (aka BOARD_DIR), if it contains a board.yml meta-data file it's HWMv2, otherwise it's HWMv1
  • then, if we found a SoC directory (aka SOC_FULL_DIR) it's HWMv2 (SOC_FULL_DIR actually exists for HWMv1 too, but it's not eventually made public as an external CMake cache variable)

When the hardware model has not been identified, HWMv1 is assumed.

This permits to get the right paths to all available metadata files (board, Soc, test runner, etc).

HWMv2 targets (BOARD) are parsed into board name, version, and qualifiers. Omitted (unique) SoC and (default) version may be retrieved from metadata files.

The uname command has been updated accordingly.

/
> uname -mp

uname-mp

Note: the deprecated board command has been removed (superseded by uname).

Command output redirection

  • when the command whose output is being redirected fails, do not create a new empty file, or overwrite an existing file with an empty file
  • when the command whose output should be appended to an existing file fails, do not add a blank line at the end of the file
  • when the command output should be appended to an existing structured file (HTML/SVG), abort gracefully and leave the file untouched if the contents do not match the expected format
  • fixed an issue where command output redirection would generate empty contents with the latest version of the rich library (issue #7)
  • updated preferences

SVG

  • workaround a rich library issue where the last line of captured outputs would be truncated (issue #8)
  • fixed geometry issues, especially when appending to existing SVG files
  • define the document level viewBox without which the rendering of the generated SVG file seems unpredictable when used in an HTML <img>
  • fixed malformed CSS definition of the default Fira Code font
  • configurable title bar (optional macOS-like window buttons and title)

HTML

  • workaround a rich library issue where hyperlinks (e.g. to binding files) would be rendered as unvisited links if relying on inline CSS styles to append a command output to an existing HTML file (issue #9)
  • fixed and issue where the CSS font style would not be properly inherited, and the output rendered with a non monospace font
  • added a preference for configuring the font size
  • the default theme has been changed so that HTML and SVG files for the same command look the same

Full Changelog

Full Changelog: v0.2.3.1...v0.2.4

Assets 2
Loading