This chapter focuses on the Buildroot system (root@ user, eglfs backend). In the examples, the board IP is 192.168.1.100 and the Ubuntu VM IP is 192.168.1.200 — replace with your actual values.

Board Display Backend Configuration (Must Read)

RK3576 features a Mali GPU. Qt applications render output directly via the eglfs_kms backend using KMS/DRM, without requiring X11 or Wayland. eglfs requires exclusive access to the DRM device — if another program (such as a Wayland compositor) is using the display device, the Qt program will experience screen flickering and report Could not queue DRM page flip (Device or resource busy) errors.

Disabling Weston (First-Time Setup, One-Time Operation)

The default Buildroot image auto-starts Weston (a Wayland compositor), which occupies the DRM device. It must be disabled for eglfs mode:

# Check if weston is running
fuser /dev/dri/card0
# If there is output (e.g., 766), a process is occupying the device

# Disable weston auto-start and reboot
chmod -x /etc/init.d/S49weston
reboot

After reboot, Weston no longer starts, the DRM device is free, and Qt programs can use it exclusively.

If you need to restore Weston later, run chmod +x /etc/init.d/S49weston and reboot.

Confirming the Display Device

ls /sys/class/drm/card0-*
cat /sys/class/drm/card0-*/status

Find the device name with connected status (e.g., HDMI-A-1), then edit /etc/qt-eglfs-kms.conf:

{
	"device": "/dev/dri/card0",
	"hwcursor": false,
	"outputs": [
		{
			"name": "HDMI-A-1",
			"mode": "1920x1080"
		}
	]
}

"hwcursor": false disables the hardware cursor to avoid Failed to move cursor on screen error spam. If a mouse pointer is needed, Qt will automatically use a software cursor instead.

Environment Variables

The following must be set before running Qt applications:

export QT_QPA_PLATFORM=eglfs
export QT_QPA_EGLFS_INTEGRATION=eglfs_kms
export QT_QPA_EGLFS_KMS_CONFIG=/etc/qt-eglfs-kms.conf
export QT_QPA_FONTDIR=/usr/share/fonts/dejavu
export QT_PLUGIN_PATH=/usr/lib/qt/plugins

For pure touchscreen scenarios (no mouse pointer needed), additionally set:

export QT_QPA_EGLFS_HIDECURSOR=1

If you need both mouse and touch to coexist, do not set HIDECURSOR. The "hwcursor": false in the KMS configuration makes Qt use a software cursor, so the mouse pointer displays normally without triggering hardware cursor errors.

Variable	Description
QT_QPA_PLATFORM	Platform backend; eglfs renders directly via EGL/OpenGL ES without X11
QT_QPA_EGLFS_INTEGRATION	Set to eglfs_kms to control display output via kernel KMS/DRM
QT_QPA_EGLFS_KMS_CONFIG	Path to the KMS configuration file
QT_QPA_FONTDIR	Must point to a directory directly containing .ttf files; Qt does not recursively search subdirectories
QT_PLUGIN_PATH	Qt plugin path containing input device (libinput/evdev) and platform plugins
QT_QPA_EGLFS_HIDECURSOR	Set to 1 to hide the cursor for pure touchscreen scenarios. If not set, a software cursor is displayed

It is recommended to add these exports to /etc/profile on the board to avoid setting them manually each time.

Deployment Methods

SCP + SSH

cmake --build build && scp build/tspi-sysmonitor root@192.168.1.100:/root/ && \
  ssh root@192.168.1.100 "/root/tspi-sysmonitor"

NFS Mount (Recommended)

For NFS configuration, see Communication Channels — NFS Sharing.

Set the CMake install path directly to the NFS shared directory — compile and deploy in one step:

cmake -B build -DCMAKE_INSTALL_PREFIX=/srv/nfs/qt-dev

# After each code change:
cmake --build build && cmake --install build

# Run directly on the board (or trigger via SSH)
ssh root@192.168.1.100 "/mnt/nfs/bin/tspi-sysmonitor"

One-command compile and restart the application on the board:

cmake --build build && cmake --install build && \
  ssh root@192.168.1.100 "pkill -f tspi-sysmonitor 2>/dev/null; /mnt/nfs/bin/tspi-sysmonitor &"

The SSH commands above omit environment variables, assuming they have been written to /etc/profile. Otherwise, prepend the full exports before the command.

Common NFS Issues:

• "Connection refused": Ubuntu firewall is not allowing NFS -> sudo ufw allow from 192.168.1.0/24 to any port nfs
• Files are read-only: /etc/exports is missing the rw option -> modify and run sudo exportfs -ra
• Program cannot execute: NFS was mounted with noexec -> remount with the exec option

ADB

Connect via OTG Type-C to the Windows host. See ADB Usage Tutorial for details.

adb push tspi-sysmonitor /root/
adb shell "chmod +x /root/tspi-sysmonitor && /root/tspi-sysmonitor"

GDB Remote Debugging

GDB Source

Buildroot does not compile a cross GDB by default. Use the SDK-bundled aarch64-rockchip1031-linux-gnu-gdb (included with GCC 10.3) — debugging programs compiled with GCC 12.4 works without issues.

Compiling a Debug Build

cmake -B build \
    -DCMAKE_TOOLCHAIN_FILE=/home/lckfb/TaishanPi-3-Linux/buildroot/output/rockchip_rk3576/host/share/buildroot/toolchainfile.cmake \
    -DCMAKE_PREFIX_PATH=/home/lckfb/TaishanPi-3-Linux/buildroot/output/rockchip_rk3576/staging/usr/lib/cmake \
    -DCMAKE_BUILD_TYPE=Debug
cmake --build build

Debugging Workflow

On the board, start gdbserver (if gdbserver is not available, enable BR2_PACKAGE_GDB_SERVER in Buildroot):

gdbserver :2345 /root/tspi-sysmonitor

On the Ubuntu VM, connect:

/home/lckfb/TaishanPi-3-Linux/prebuilts/gcc/linux-x86/aarch64/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/bin/aarch64-rockchip1031-linux-gnu-gdb build/tspi-sysmonitor

(gdb) target remote 192.168.1.100:2345
(gdb) break main
(gdb) continue

Core Dump Analysis

# On the board
ulimit -c unlimited && ./tspi-sysmonitor

# Retrieve and analyze on the Ubuntu VM
scp root@192.168.1.100:/tmp/core-* /tmp/
aarch64-rockchip1031-linux-gnu-gdb build/tspi-sysmonitor /tmp/core-tspi-sysmonitor-1234
(gdb) bt

Common Troubleshooting

Error Message	Cause	Solution
cannot open shared object file: libQt5Widgets.so.5	Qt libraries not in search path	export LD_LIBRARY_PATH=/usr/lib:$LD_LIBRARY_PATH
Could not find the Qt platform plugin "eglfs"	Platform plugin path not set	Run find / -name "libqeglfs.so" to locate it, then set QT_QPA_PLATFORM_PLUGIN_PATH
Could not create the EGL display	GPU driver not loaded	Check ls /dev/dri/ and dmesg | grep -i mali; temporarily fall back to linuxfb
Permission denied	Missing execute permission or NFS noexec	chmod +x or remount NFS with exec option

Next Steps

Next step: Buildroot Application Integration