v0.2.4

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:

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:

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):

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:

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

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

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

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

v0.2.3.1

Maintenance release, pin the version of the rich library as a workaround for Command output redirect generates "empty" files (#7).

Full Changelog: v0.2.3...v0.2.3.1

v0.2.3

New and Noteworthy

• Upgrades the packaged version of the python-devicetree library to Zephyr 3.7.0.
• Initial support for Zephyr Hardware Model v2, especially the changes to the board naming scheme and SoC files. Should address a few issues with Zephyr 3.7.0.
• Introduce a new uname command which prints system information (Zephyr environment, board, SoC). Supersedes the board builtin.

/
> uname --board -l
    Board: nrf52840dk/nrf52840                                                                 
BOARD_DIR: /path/to/zephyr/boards/nordic/nrf52840dk [↗]
      DTS: BOARD_DIR/nrf52840dk_nrf52840.dts [↗]                                               
     YAML: nrf52840dk_nrf52840.yaml [↗]                                                        
           identifier: nrf52840dk/nrf52840                                                     
           name: nRF52840-DK-NRF52840                                                          
           type: mcu                                                                           
           arch: arm                                                                           
           ram: 256                                                                            
           flash: 1024                                                                         
           toolchain:                                                                          
             - zephyr                                                                          
             - gnuarmemb                                                                       
             - xtools                                                                          
           supported:                                                                          
             - adc                                                                             
             - arduino_gpio                                                                    
             - arduino_i2c                                                                     
             - arduino_serial                                                                  
             - arduino_spi                                                                     
             - ble                                                                             
             - counter                                                                         
             - gpio                                                                            
             - i2c                                                                             
             - i2s                                                                             
             - pwm                                                                             
             - spi                                                                             
             - usb_device                                                                      
             - usbd                                                                            
             - watchdog                                                                        
             - netif:openthread                                                                
           vendor: nordic             

/
> uname -ol
 ZEPHYR_BASE: /path/to/zephyr [↗]      
     Release: Zephyr-RTOS v3.7.0                                               
   Toolchain: gnuarmemb [↗]                                                    
  Devicetree: /path/to/application/build/zephyr/zephyr.dts [↗]
    Bindings: /path/to/external/module/dts/bindings [↗]           
              ZEPHYR_BASE/dts/bindings [↗]                                     
Vendors file: ZEPHYR_BASE/dts/bindings/vendor-prefixes.txt [↗]                 
 Application: sample-bme68x-iaq [↗]                                                           

• The board builtin is deprecated and will output a warning message. It will be removed in DTSh 0.2.4.
• More informative errors messages and status when opening and parsing YAML/DTS files

/
> board -l
The board builtin is deprecated: please use the uname command instead.

Inaccessible or malformed YAML file:                                                                       
  /path/to/zephyr/boards/nordic/nrf52840dk/nrf52840dk/nrf52840.yaml
  No such file or directory                                                                                
board: failed to open board file (YAML)

• Updates default preferences and theme
• Example alternative preferences file for redirecting commands output to HTML. Example alternative more sober theme and preferences files.
• Initiates a FAQ & Tips entry to the documentation

Full Changelog

Full Changelog: v0.2.2...v0.2.3

v0.2.2

New and Noteworthy

Noteworthy changes bellow, besides a few minor bug fixes.

board

Simple new command to print board information:

• description from YAML
• board file (DTS)

   /
   > board
   identifier: bbc_microbit
   name: BBC Micro:Bit
   type: mcu
   arch: arm
   toolchain:
     - zephyr
     - gnuarmemb
     - xtools
   ram: 16
   testing:
   ignore_tags:
     - net
   supported:
     - ble
     - i2c
     - gpio
     - pwm

Patched edtlib library

The PropertySec.path API in the python-devicetree library wrongly tells all properties originate from the top-level binding file, which causes the cat command to show misleading and confusing paths (see issue #5).

We've proposed a patch upstream, but its review clearly is not a priority (the underlying issue has no consequence on Zephyr use of the library).

We apply this patch here:

• will actually fix the cat command, and does not otherwise break DTSh
• can't break Zephyr in any way (will still use its own unpatched version of the python-devicetree library, see issue #2)

Full Changelog

Full Changelog: v0.2.1...v0.2.2

v0.2.1

New and Noteworthy

cat

The ls, tree and find commands all eventually enumerate nodes, and the --format option permits to select columns among a predefined set of properties.

The new cat built-in permits to access:

• the values of all defined node properties
• almost complete contents of node bindings and property specifications

It's simple while quite handy:

/
> cat &qspi/$* -l
  Property                       Type          Value
 ────────────────────────────────────────────────────────────────────────────────────────
 interrupts                     array         < 0x29 0x01 >
 pinctrl-0                      phandles      < &qspi_default >
 reg                            array         < 0x40029000 0x1000 0x12000000 0x08000000 >
 status                         string        "okay"
 compatible                     string-array  "nordic,nrf-qspi"
 reg-names                      string-array  "qspi", "qspi_mm"
 wakeup-source                  boolean       false
 zephyr,pm-device-runtime-auto  boolean       false
 pinctrl-1                      phandles      < &qspi_sleep >
 pinctrl-names                  string-array  "default", "sleep"

/
> cat &qspi/mx25r6435f@0$quad-enable-requirements -Bl
           Name: quad-enable-requirements                                      
           From: nordic,qspi-nor.yaml                                          
           Type: string                                                        
       Required: No                                                            
     Deprecated: No                                                            
           Enum: "NONE", "S2B1v1", "S1B6", "S2B7", "S2B1v4", "S2B1v5", "S2B1v6"
          Const: Not a const                                                   
        Default: "S1B6"                                                        
Specifier Space: No specifier space         

/
> cat &led0 -lB
    Compatible: This binding does not define a compatible string.
           Bus: This binding neither provides nor depends on buses.
Child-Bindings: gpio-leds
                └── GPIO LED child node

Property  Type           Description
────────────────────────────────────────────────────────────────────────────────────────
gpios     phandle-array
label     string         Human readable string describing the LED. It can be used by an…

Batch mode

For scripting and automation, DTSh can now execute non-interactively:

• a series of commands passed as program arguments: dtsh -c CMD1 -c CMD2 ...
• commands form a script file: dtsh -f FILE

The -i --interactive option then permits to enter the interactive loop after the batch commands have been executed, as desired.

The -c option is especially practical on POSIX shells, where you can define aliases, e.g.:

# An alias to export the devicetree to HTML without leaving the operating system shell.
alias dts2html='dtsh -c "tree --format NKiYcd > devicetree.html"'

Combined with the pager, scripts allow to create simple presentations:

# First "slide"
#
# Start with the tree of buses and connected devices: speaker will press "q"  when done
find --with-bus * --OR --on-bus * --format NYcd -T --pager

# Let's look at the Flash partitions.
#
# 1st, the controller: : speaker will press "q"  when done
cat &flash_controller -A --pager
# Then partitions with addresses and sizes: speaker will press "q"  when done
tree &flash_controller --format NrC --pager

# Etc.

# If the script is run with "-i", DTSh will enter the interactive loop
# after the last command: speaker can then navigate the command history
# to re-open "slides" while answering questions.

Many thanks to @pillo79 who pushed this forward and contributed to the implementation (PR #4).

Updated output redirection policy

By default, DTSh does not permit to overwrite existing files when redirecting commands output.
While this is a welcome precaution, this also breaks appending (>>):

/
> ls > ls.txt

/
> ls >> ls.txt
dtsh: file exists: 'ls.txt'

The preference pref_fs_no_overwrite is still set by default, but now bypassed when appending commands output.

Set the new pref_fs_no_overwrite_strict preference to never overwrite existing files.

Full Changelog

v0.2.0...v0.2.1

v0.2.0

Mostly patch the DTSh v0.2.0-rc1 code base from the upstream RFC for a better behavior when not distributed as a Zephyr extension to West.
Make this the default project's branch, published as DTSh v0.2.0.

Validate ZEPHYR_BASE

When ZEPHYR_BASE isn't explicitly set, and can't be retrieved from a CMake cache file, DTSh eventually derived it from some __file__ location. But when not distributed within Zephyr, this value is likely to be invalid. DTSh now validates this path by looking for a ZEPHYR_BASE/Kconfig.zephyr file.

Search binding directories for the vendors file

When no valid ZEPHYR_BASE can't be found, but the user has explicitly set some binding directories, search those for vendor-prefixes.txt.

Match dependency ordinals

The new criterion --with-dts-ord EXPR will find nodes whose dependency ordinal (aka DTS order) matches the integer expression EXPR. May help to figure out __device_dts_ord_xxx errors.

Full Changelog: v0.2.0-rc1...v0.2.0

DTSh 0.2.0-RC1

Mirrors and packages RFC - DTSh: DTS file viewer with a shell-like command line interface.

Should be compatible with Zephyr 3.5.x and 3.6.0-RC1.

Detailed documentation and examples: DTSh User Guide

This release is deprecated: if already installed please update to at least v0.2.0

v0.1.0 beta-2

New and Noteworthy

Update the bundled python-devicetree library to Zephyr 3.5.0.

Full Changelog: v0.1.0b1...v0.1.0b2

v0.1.0 beta-1

New and Noteworthy

Update the bundled python-devicetree library to Zephyr 3.4.0.

Full Changelog: v0.1.0a6...v0.1.0b1

v0.1.0 alpha-6

New and Noteworthy

Bundling the EDT library

This release bundles the EDT library (edtlib) from Zephyr 3.3.0, instead of installing the devicetree package from PyPI: this approach allows to update the library implementation and API dtsh can depend on more frequently and reliably.

See 5e803eb ci: bundle devicetree Python package.

Prefer gnureadline on macOS

On BSD-like systems (e.g. macOS), dtsh will try to install the gnureadline package, and to load the readline implementation from there instead of from the Python standard library.

Should improve the overall user experience on these platforms.

See 14dc590 rl: do not assume readline is really a standard Python package.

Fix Python type hinting

Type hinting in dtsh should:

• be compatible with Python 3.8 (Zephyr minimal requirement)
• try to be compatible with at least Python 3.9

Alternative syntax for unions (e.g T1 | T2) requires Python 3.10: rewrite occurrences to Unions or Optionals.

Subscripting builtin classes (e.g. list[T]) requires Python 3.9: rewrite occurrences using the typing package (e.g. typing.List[T]), even if Python 3.9+ in turn deprecates this use of the typing package in favor of subscripting the builtin types (sic).

dtsh should now run fine on Python 3.8+ as expected.

See aa0a96b ci: type hinting should be compatible with Python 3.8.

Platform dependent paths to configuration directory and files

See 3c59fb0 config: expected configuration paths should be platform dependent.

Changes since v0.1.0a4

See the full Changelog: v0.1.0a4...v0.1.0a6