From a860d9d7360bf90e4c8b407cfd0e4db4d0a108cb Mon Sep 17 00:00:00 2001 From: Christophe Dufaza Date: Fri, 31 Oct 2025 10:54:01 +0100 Subject: [PATCH] doc: develop: manifests: external: add dtsh Introduce documentation for using dtsh (a Devicetree Shell) as an external module in Zephyr. This module installs a West extension. See also RFC #59863. Signed-off-by: Christophe Dufaza --- doc/develop/manifest/external/dtsh.rst | 105 +++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 doc/develop/manifest/external/dtsh.rst diff --git a/doc/develop/manifest/external/dtsh.rst b/doc/develop/manifest/external/dtsh.rst new file mode 100644 index 0000000000000..be511c3a9c28e --- /dev/null +++ b/doc/develop/manifest/external/dtsh.rst @@ -0,0 +1,105 @@ +.. _external_module_dtsh: + +dtsh +####################### + +Introduction +************ + +`DTSh `_ is an interactive DTS file viewer with +a shell-like command line interface: + +- easily *navigate* and *visualize* the devicetree +- find nodes based on e.g. supported bus protocols, bindings, generated IRQs, + memory size, or keywords like "sensor" or "PWM" +- redirect commands output to files (text, HTML, SVG) + to document hardware configurations or simply take notes +- contextual auto-completion, commands history, semantic highlighting, user profiles +- script-able (aka batch modes) + +This Zephyr module adds DTSh as a West extension to your Zephyr workspace. + + +Usage with Zephyr +***************** + +To install the DTSh module, you will need to define your own manifest file, +or pull it in by adding a submanifest. + +E.g. assuming the same paths as in `Zephyr Getting Started Guide`_, +create ``zephyrproject/zephyr/submanifests/dtsh.yaml`` with the following content: + +.. code-block:: yaml + + manifest: + projects: + - name: dtsh + url: https://github.com/dottspina/dtsh.git + revision: zephyr + path: modules/tools/dtsh + west-commands: scripts/west-commands.yml + + +Then update the workspace and install DTSh requirements: + +.. code-block:: sh + + west update dtsh + west packages -m dtsh pip --install + +.. note:: + + ``west update dtsh`` will fetch all tags from the `DTSh project `_: ignore them, + they don't point to versions of this Zephyr module, and are entirely irrelevant here. + + +The West command +***************** + +Once installed, this project/module should provide the ``west dtsh`` command. + +.. code-block:: none + + $ west build + $ west dtsh + dtsh (0.2.5-zephyr): Shell-like interface with Devicetree + How to exit: q, or quit, or exit, or press Ctrl-D + + / + > cd &flash_controller + + /soc/flash-controller@4001e000 + > find -E --also-known-as (image|storage).* --format NKd -T + Also Known As Description + ─────────────────────────────────────────────────────────────────────────────────── + flash-controller@4001e000 flash_controller Nordic NVMC (Non-Volatile Memory Controller) + └── flash@0 flash0 Flash node + └── partitions This binding is used to describe fixed partitions… + ├── partition@c000 image-0, slot0_partition Each child node of the fixed-partitions node represents… + ├── partition@82000 image-1, slot1_partition Each child node of the fixed-partitions node represents… + └── partition@f8000 storage, storage_partition Each child node of the fixed-partitions node represents… + + +For the full West command synopsis, run ``west dtsh -h``. + +.. note:: + + It's recommended to install the module to its default location, ``modules/tools/dtsh``. + Otherwise, be sure to set the ``ZEPHYR_BASE`` environment variable before running ``west dtsh``. + + +Reference +********* + +- `DTSh project `_ +- `DTSh Handbook `_ +- `dtsh module `_ + + +.. _DTSh-project: https://github.com/dottspina/dtsh + +.. _DTSh-Handbook: https://dottspina.github.io/dtsh/handbook.html + +.. _dtsh-module: https://github.com/dottspina/dtsh/tree/zephyr + +.. _Zephyr Getting Started Guide: https://docs.zephyrproject.org/latest/develop/getting_started/