Introduction

Welcome to dtup. A devicetree toolchain for better developer experience when developing devicetrees in an embedded environment.

dtup is an open-source and free-software project. It’s repository is hosted on GitHub under this URL: https://github.com/omekina/dtup

In this book we will take a look at how to get started with dtup and how to run it’s tools on your project. As the project is written in Rust—it has extended cross-platform compatibility and you should be fine whether running it on Linux, MacOS or even Windows. It’s also somewhat Android-compatible, but that’s not officially supported.

The goals of dtup

dtup aims to be easy-to-use and friendly to newcomers to devicetree development. It over-explains everything instead of just telling you something is wrong somewhere near some line. This is the primary goal—to achieve ideal error verbosity so the developer using this toolchain can instantly tell what’s wrong.

Current scope

Currently, dtup is a validator and a visualizer. It can be used to view or check a devicetree before submitting a compilation job and building the whole system with a potentially broken devicetree.

Installation

Since binary builds for direct downloads are planned, but not yet available for stability reasons—you will have to build the project from source yourself. But don’t worry, thanks to Rust’s mature ecosystem, that should be a pretty easy task.

We will need to obtain the source code of the dtup project and then we’ll need to install the build dependencies. After that we can jump right to creating device trees.

So go ahead and jump to the next chapter.

Obtaining the source code

Now there are two main options to do that:

a) Clone using Git

To clone the repo directly, you will need the Git command installed system-wide. Please refer to Git’s documentation (https://git-scm.com/) for an installation guide.

Once you have Git installed, ensure that you have a terminal open in a directory in which you wish to create a dtup package directory. When you have the place for dtup, just type the following command:

git clone https://github.com/omekina/dtup

This will create a new directory in your current working path and will name it dtup. Once you have that, continue reading in the next chapter.

b) Download the source-code zip bundle

Use this link to download the package directly: https://github.com/omekina/dtup/archive/refs/heads/main.zip

Once you have the zip archive downloaded, unpack it through your file manager. It should contain a single directory with the name dtup. We will need that to continue. When you have it unpacked and have the dtup directory prepared—continue reading in the next chapter.

Installing dependencies

We will need three main things:

• Rust toolchain (rustc, cargo, stdlib)
• Bun
• GNU Make

So install all of them by using the guides bellow.

Rust

If you’re a Rust developer yourself, you probably know this drill already and will choose your own way. And if you are not, then let’s make it easy for you by using the simplest approach.

Go ahead and install rustup by following the instructions on the website and then the instructions in the terminal: https://rustup.rs/

Once you have rustup, you should run:

rustup default stable

That will pull all the necessary things to compile a standard Rust project. And if you followed all the instructions given during rustup’s installation process, you should have Rust ready and waiting to be used.

Bun

This is the other thing we’ll need to install. As the dtup viewer is a web application, it needs a bundler to bundle it’s client files.

You can install Bun by following this guide: https://bun.sh/

After you installed Bun, just try running the following command in your terminal to check if we have it up and ready:

bun -v

If it prints a version (three dot-separated numbers), then you installed it correctly.

GNU Make

If you are on Linux you most probably already have make installed. Just to check, try running the following command:

make -v

It should print a nice banner with some information like the version, license, warranty, …

If it doesn’t and says that the command does not exist, you will need to install it.

Linux

Please check your distribution’s package manager reference to see the name of the package and install it. Sadly, there are just too many Linux distributions to cover in this guide.

Mac

Use homebrew to install make: https://formulae.brew.sh/formula/make

Windows

Use GnuWin32—follow the guide on this website: https://gnuwin32.sourceforge.net/packages/make.htm

Wrapping up

Please make sure you installed all of the three dependencies (Rust, Bun, Make) before moving to the next chapter.

Now… give yourself a big pat on the back. You installed all the dependencies and everything should be smooth sailing from here on.

dtq

dtq is a command-line utility to query information directly from the source files from your filesystem. It processes and builds the tree directly in RAM and prints out the structure for you. There is no middle-step needed (like compiling the tree into devicetree binary format).

Make sure you followed the installation before proceeding.

Now, if you are using this tool for the first time, you will need to build it. In such case, follow the building guide.

Building dtq

Locate the dtup directory which you created in the download part of this book. If you have all the dependencies installed, you should be able to build dtq simply by running a build through cargo. Open a terminal in the previously mentioned dtup directory and run:

cargo build -p dtq --release

Now wait for the build to finish. After the build finishes you should see a binary in dtup/target/release/dtq (where dtup is the directory in which we have the opened terminal).

Now the simplest way to use this binary is to copy it into the directory in which you have your devicetree source files. You can also install it system-wide, but that might not work for some operating systems, so if you’re not sure—rather copy it into the same directory in which you develop your devicetrees.

Running dtq

In the previous chapter you have prepared the executable dtq binary into the directory in which you develop your devicetrees.

Now go ahead and open a terminal in that directory. Now you need to locate your devicetree entrypoint file—the file which you pass to the compiler as an argument. Now you should run dtq on it.

./dtq <file>

Where <file> is the path to your entrypoint file (relative to the directory in which you opened your terminal just now).

After running that—dtq should jump in and start running. If your devicetree is somehow incorrect, dtq will emit errors and refuse to print the processed tree. If there are only some non-fatal warnings dtq will print them and then the compilation time and the tree. If there are no problems, then dtq will only print out the compilation time and the tree.

dtview

dtview is a hot-reloading web app to view the visual representation of the tree and, when needed, report errors or warnings. The main component is the web server which processes your tree in RAM and serves a HTTP connection, so you can view the tree in real-time in your browser.

Make sure you followed the installation before proceeding.

If you are using this tool for the first time, you will need to build it. In such case, follow the building guide.

Building dtview

Locate the dtup directory which you created in the download part of this book. If you have all the dependencies installed, you should be able to build dtview simply by running a build through cargo. Open a terminal in the dtup/dtview directory and run:

make

Now wait for the build to finish. After the build finishes you should see a binary in dtup/target/debug/dtview (where dtup is the directory where we downloaded the dtup code to).

Now the simplest way to use this binary is to copy it into the directory in which you have your devicetree source files. You can also install it system-wide, but that might not work for some operating systems, so if you’re not sure—rather copy it into the same directory in which you develop your devicetrees.

Running dtview

In the previous chapter you have prepared the executable dtview binary into the directory in which you develop your devicetrees.

Now go ahead and open a terminal in that directory. Now you need to locate your devicetree entrypoint file—the file which you pass to the compiler as an argument. Now you should run dtview on it.

./dtview <file>

Where <file> is the path to your entrypoint file (relative to the directory in which you opened your terminal just now).

Viewing the tree

This command will start the dtview server and give your tree to it. dtview will start listening on http://localhost:8080. So as it’s running, open a browser next to it and go to the following URL: http://localhost:8080. You either should see your tree already, or you should see an error and will be told to check the console. Don’t worry—that’s intentional. If you see an error, just look at the terminal in which you have the dtview server running, it will show you everything.

Live-updating

Now once you have it all set-up you can start modifying your devicetree source files. Each time you save the file in your editor, you should see the tree in your browser get immediately updated. If there is an error, the tree will disappear and you’ll have to look at the console output to read it. Note that errors might get moved to the browser as the project evolves.

Stopping the server

If you wish to stop the server, jump into the terminal window and press Ctrl+C anytime. The server will perform a clean-up and should end within a second.