Device Tree Overlay for a Custom FPGA Peripheral
Load a bitstream and its driver binding at runtime on PetaLinux without rebuilding the image.
- Runs out of the box: no
- Tests: yes
- CI: no
- Docs: yes
- Used in production: no
Purpose#
A worked example of attaching a custom programmable-logic peripheral to a running Linux system. A Vivado project produces a bitstream for a small register block; a device tree overlay declares the peripheral; a minimal platform driver exposes it through sysfs.
The example loads the bitstream and applies the overlay from a script, then unloads both, so peripheral changes can be tested without rebuilding or reflashing the whole image.
What you will learn#
- Generate a bitstream and hardware description for a custom register block
- Write a device tree overlay and apply it at runtime
- Bind a minimal platform driver and expose registers through sysfs
Technologies & features#
- Technologies
- VHDLCZynq-7000PetaLinuxVivado
- Features
- Device Tree ConfigurationFPGA Bitstream Integration
- Topics
- Embedded/Linuxprimary
Lessons learned#
- Worked
Loading the overlay at runtime shortened the edit-test loop for the register map from a full image rebuild to under a minute.
- Limitation
Unloading the overlay while a userspace process holds the device open can hang; the script refuses to unload while the device is in use.
- Note
The overlay's compatible string must match the driver exactly; a one-character mismatch fails silently, so the load script now checks that the driver bound.
Try it#
git clone https://git.example.internal/embedded-platforms/fpga-overlay-demo.git
cd fpga-overlay-demo
petalinux-build # needs the PetaLinux tools
# on the board:
./scripts/load-peripheral.sh demo_regs.bit demo_regs.dtbo
cat /sys/devices/platform/demo-regs/versionCommands come from the owner’s README. Credentials are never stored here.
