EGLFS: Qt ohne Fenstersystem auf Embedded-Hardware betreiben

Kurz gesagt: Auf einem Embedded-Gerät gibt es meist keinen Fenstermanager, keinen Desktop und keine Maus – nur eine Anwendung, die den Bildschirm ganz für sich hat. Genau dafür ist EGLFS gebaut: Das Qt-Plattform-Plugin zeichnet über EGL und OpenGL ES direkt auf die Grafikhardware, ohne X11 oder Wayland dazwischen. Das spart Speicher, Startzeit und eine ganze Schicht möglicher Fehler. Der Preis ist, dass man die Schicht darunter kennen muss, sobald etwas nicht funktioniert.

Was EGLFS eigentlich ist

Qt spricht mit dem Betriebssystem über ein Plattform-Plugin (QPA). Auf dem Desktop ist das X11, Wayland oder Cocoa; auf einem Gerät ohne Fenstersystem übernimmt EGLFS. Es besorgt sich über EGL eine Zeichenfläche, die den gesamten Bildschirm einnimmt, und rendert Qt Quick darauf über OpenGL ES – hardwarebeschleunigt, sofern die GPU einen Treiber mitbringt.

Die Auswahl passiert über eine Umgebungsvariable:

export QT_QPA_PLATFORM=eglfs
./meine-anwendung

Für Systeme ganz ohne GPU gibt es LinuxFB, das direkt in den Framebuffer schreibt und in Software rastert. Das ist deutlich langsamer und für animierte Oberflächen kaum brauchbar, rettet aber Projekte auf Hardware ohne Beschleunigung.

Die Backends – der Punkt, an dem es meist klemmt

EGLFS ist kein monolithisches Stück Code, sondern wählt eine gerätespezifische Integration. Auf modernen SoCs ist das üblicherweise die KMS/DRM-Variante, die über die Standard-Schnittstellen des Kernels arbeitet. Daneben existieren herstellerspezifische Integrationen für Grafikkerne, deren Treiber eigene Wege gehen.

Welche Integration gezogen wird, entscheidet Qt zur Laufzeit anhand dessen, was auf dem System vorhanden ist – und genau hier entsteht das häufigste Fehlerbild. Passt die gewählte Integration nicht zur Hardware, startet die Anwendung ohne Fehlermeldung, und der Bildschirm bleibt schwarz. Der erste Griff sollte deshalb immer zur Diagnoseausgabe gehen:

export QT_LOGGING_RULES="qt.qpa.*=true"
./meine-anwendung

Qt schreibt dann auf, welche Integration geladen wurde, welche Ausgänge gefunden wurden und welcher Modus gesetzt wurde. In den meisten Fällen ist damit klar, ob das Problem bei der GPU-Anbindung, beim Ausgang oder bei den Rechten liegt.

Displays konfigurieren

Ohne weitere Angaben nimmt EGLFS den ersten verbundenen Ausgang und dessen bevorzugten Modus. Für ein Produkt reicht das selten – Auflösung, Bildwiederholrate und die Frage, welcher Ausgang überhaupt bespielt wird, gehören festgelegt. Das geschieht über eine JSON-Datei:

{
  "device": "/dev/dri/card0",
  "outputs": [
    { "name": "HDMI1", "mode": "1920x1080", "primary": true },
    { "name": "LVDS1", "mode": "off" }
  ]
}

export QT_QPA_EGLFS_KMS_CONFIG=/etc/qt-kms.json

Damit ist reproduzierbar festgelegt, was das Gerät anzeigt – unabhängig davon, was gerade angesteckt ist. Für Geräte mit zwei Displays wird zusätzlich der primäre Ausgang markiert, weil Qt Quick standardmäßig nur eine Fläche bespielt.

Eingabe: ohne Maus, aber mit Touch

Ohne Fenstersystem gibt es auch keine zentrale Eingabeverwaltung. Qt liest Eingabegeräte entweder direkt über evdev oder über libinput – letzteres ist die robustere Wahl, weil es Gerätetypen erkennt und Gesten vorverarbeitet.

Zwei Punkte fallen in der Praxis auf. Erstens die Zugriffsrechte: Läuft die Anwendung nicht als root, braucht der ausführende Benutzer Zugriff auf die Geräte unter /dev/input und auf die DRM-Geräte. Das über Gruppen und udev-Regeln sauber zu lösen ist Teil der Systemkonfiguration und wird gern vergessen, bis der erste Test mit einem unprivilegierten Dienst läuft. Zweitens die Touch-Kalibrierung: Ein resistiver oder schlecht kalibrierter Touch liefert Koordinaten, die nicht zum Bild passen – erkennbar daran, dass Berührungen konsistent versetzt ankommen.

Ein sichtbarer Mauszeiger ist auf einem Touch-Gerät selten erwünscht und lässt sich abschalten:

export QT_QPA_EGLFS_HIDECURSOR=1

Was sich mit Qt 6 geändert hat

Qt Quick rendert seit Qt 6 nicht mehr direkt gegen OpenGL, sondern über die RHI-Abstraktion. Für EGLFS-Setups bedeutet das: Annahmen, die unter Qt 5 galten, sollten nach einer Migration erneut geprüft werden – insbesondere, wenn eigener Code direkt OpenGL-Aufrufe absetzt. Die Reihenfolge, in der man eine solche Migration angeht, haben wir im Beitrag Von Qt 5 auf Qt 6 migrieren beschrieben.

Typische Fehlerbilder

Symptom	Wahrscheinliche Ursache
Schwarzer Bildschirm, Anwendung läuft	Falsche EGLFS-Integration oder falscher Ausgang gewählt
Start bricht mit EGL-Fehler ab	GPU-Treiber oder EGL-Bibliothek fehlt im Image
Bild erscheint, aber keine Eingabe	Rechte auf /dev/input, oder libinput nicht im Image
Berührung kommt versetzt an	Touch nicht kalibriert oder Achsen vertauscht
Läuft als root, nicht als Dienst	Fehlende Gruppenrechte auf DRM- und Eingabegeräte
Nur ein Display bespielt	Kein primärer Ausgang in der KMS-Konfiguration gesetzt

Wann ein Compositor die bessere Antwort ist

EGLFS bedient genau einen Vollbild-Client. Sobald zwei Prozesse gleichzeitig etwas darstellen sollen – eine Hauptanwendung und ein Wartungs-Overlay, eine Video-Ebene neben der Bedienoberfläche –, ist ein Wayland-Compositor wie Weston der richtige Weg. Er kostet Speicher und Startzeit, löst dafür ein Problem, das EGLFS konstruktionsbedingt nicht lösen kann.

Die Entscheidung fällt früh und ist teuer zu revidieren, weil sie in die Architektur der Anwendung hineinreicht. Wir ordnen sie deshalb gern zu Beginn eines Projekts ein – gemeinsam mit den übrigen Fragen der Embedded-Linux-Plattform und der Qt-Entwicklung.

Fazit

EGLFS ist die schlanke, naheliegende Wahl für ein Gerät mit genau einer Bedienoberfläche: weniger Schichten, weniger Speicher, schnellerer Start. Der Preis ist, dass man beim ersten schwarzen Bildschirm eine Ebene tiefer schauen muss – auf Backend, Ausgang und Rechte. Mit der eingeschalteten QPA-Diagnose und einer festgeschriebenen KMS-Konfiguration wird daraus eine Sache von Minuten statt von Tagen. Diese Themen sind auch Teil unserer Qt- und QML-Schulung; wenn eine Oberfläche auf Ihrer Zielhardware partout nicht erscheinen will, schauen wir gerne mit Ihnen darauf.