What You Will Learn

• Why the scope of a board port depends entirely on how similar your hardware is to an existing
  supported board
• How Linux organises architecture-specific code differently across x86, PowerPC, and ARM
• How to create a new board’s device tree by adapting an existing reference board’s .dts
• How to build a standalone .dtb and how to wire it into the default build via the arch
  Makefile
• How to boot-test your new device tree and confirm the kernel recognises your board correctly

Prerequisites

• A working cross-toolchain and a kernel source tree you can already build for your target
  architecture (covered earlier in this course)
• Basic device tree syntax — nodes, properties, compatible strings
• A reference board with an existing, working device tree that is electrically close to your new
  design

How Much “Porting” Do You Actually Need?

The honest answer is: it depends entirely on how different your board is from something the
kernel already supports. If your board is a variant of an existing reference design — same SoC,
same basic memory and peripheral layout, maybe a different sensor on one I2C bus — you are looking
at a device tree edit, not new driver work. If you’re bringing up a genuinely novel SoC or a
wildly different hardware layout, the effort is much larger and out of scope for a single
lecture. This lecture covers the common, practical case: a new board around an already-supported
SoC.

Where Architecture-Specific Code Lives

Before touching anything, it helps to know how differently Linux organises per-board code across
architectures — the layout is not the same everywhere:

ARM has by far the most board- and SoC-specific files of any architecture, precisely because
there are so many ARM SoC vendors and board variants in the field. Each SoC family typically has
its own mach-* directory under arch/arm — and the name doesn’t always tell you the full
story. A single mach-* directory frequently supports several silicon generations of the same
SoC family, not just one chip.

Step 1 — Pick Your Closest Reference Board

For this walkthrough, imagine we’re bringing up a new board we’ll call ep-devboard,
built around the same SoC family as an existing, well-supported reference board. Rather than
writing a device tree from a blank file, we start from the reference board’s .dts and adapt
it — this is standard practice, and it’s exactly how real vendor board support usually starts.

Step 2 — Create the New Device Tree

Copy the reference board’s device tree source to a new file for your board, then change the
identifying fields:

$ cp arch/arm/boot/dts/soc-refboard.dts arch/arm/boot/dts/soc-ep-devboard.dts

Edit the new file’s identity so it no longer claims to be the reference board:

/dts-v1/;
#include "soc-family.dtsi"
#include "soc-refboard-common.dtsi"

/ {
    model = "EP DevBoard";
    compatible = "vendor,ep-devboard", "vendor,soc-refboard", "vendor,soc-family";
};

Keeping the reference board’s compatible string as a fallback entry (after your own) is
deliberate — it lets any driver that only matches the reference board’s compatible string still
bind correctly on your new board, until you give it its own more specific match.

Step 3 — Build the Device Tree Blob Explicitly

You can build just your new .dtb directly, which is the fastest way to iterate while you’re
still editing it:

$ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- soc-ep-devboard.dtb

Step 4 — Wire It Into the Default Build

Once the board is stable, add it to the architecture’s DTS Makefile so it gets built
automatically every time, alongside every other board in that SoC family:

# arch/arm/boot/dts/Makefile
dtb-$(CONFIG_SOC_FAMILY_XX) += \
    soc-refboard.dtb \
    soc-ep-devboard.dtb \
    [...]

Step 5 — Boot Test

Reuse the exact same kernel image you already have working for the reference board — with a
device-tree-based port, the kernel image itself usually doesn’t need to change at all. Only the
.dtb you load changes:

$ qemu-system-arm -M virt -kernel zImage -dtb soc-ep-devboard.dtb \
    -append "console=ttyAMA0 root=/dev/vda rootwait rw" -nographic

Confirm the kernel actually recognised your new board’s identity in its boot log:

Starting kernel ...
[    0.000000] Booting Linux on physical CPU 0x0
[    0.000000] Linux version 6.9.0 (builder@ep) #1 SMP PREEMPT
[    0.000000] CPU: ARMv7 Processor [413fc082] revision 2 (ARMv7)
[    0.000000] Machine model: EP DevBoard
...

That Machine model: EP DevBoard line is your confirmation: the kernel parsed your device
tree, recognised the model string you set, and is now running with your board’s identity —
not the reference board’s.

Custom Kernel Configuration for the New Board

Once boot is confirmed, it’s common to trim a full multi_v7_defconfig-style configuration
down to just what your board actually needs — dropping drivers for peripherals you don’t have
shrinks image size and reduces boot time:

$ cp arch/arm/configs/multi_v7_defconfig arch/arm/configs/ep_devboard_defconfig
$ make ARCH=arm ep_devboard_defconfig menuconfig
# disable unused drivers, save, then build normally
$ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- -j$(nproc)

Real-World Use Cases

• Custom carrier boards — a vendor SoM (system-on-module) on a bespoke carrier PCB is
  almost always a device-tree-only port, since the SoM itself is already supported
• Product variants — a company shipping three SKUs of the same product (different
  sensors, different display) typically ships three device trees against one shared kernel image
• Overlay-based development boards — rapid prototyping boards that let you swap device
  tree overlays for different peripheral add-on boards, without touching the base kernel at all

Common Mistakes and Troubleshooting

Best Practices

• Start from the closest electrically-similar reference board’s device tree, never from a blank
  file — you inherit a huge amount of correct, tested configuration for free
• Keep the reference board’s compatible string as a fallback in your new compatible
  property list during early bring-up, then remove it once your board has its own dedicated
  driver matches where needed
• Boot test after every meaningful device tree change, not just at the end — device tree bugs
  are far easier to isolate one node at a time
• Only trim the defconfig down to a board-specific config after boot is fully stable, not before

Summary and Key Takeaways

• For a board built around an already-supported SoC, “porting Linux” is mostly a device tree
  exercise, not new kernel C code
• ARM’s per-SoC-family mach-* layout under arch/arm is the most fragmented of any
  architecture, because of how many ARM SoCs and boards exist
• Copy-adapt the closest reference board’s .dts, change model and compatible, build,
  and boot test — that loop is the entire device-tree porting workflow
• The Machine model: line in the boot log is your ground-truth confirmation that the
  correct device tree was loaded

Conclusion

Device-tree-based board porting is one of the friendliest on-ramps into real embedded Linux
bring-up work, precisely because it lets you reuse almost everything the kernel community has
already tested on your reference board. Once you’re comfortable copying, adapting, and boot
testing a device tree, you’re equipped to bring up real custom hardware — a core, practical skill
in this free embedded systems course. In the next lecture we’ll cover the older,
harder path: porting a board that has no device tree support at all.

Frequently Asked Questions