Display Drivers & LVGL UI
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Display Drivers and LVGL (Light and Versatile Graphics Library) UI module in Zephyr provides a tiered architecture for rendering graphics and managing user interfaces on resource-constrained embedded systems. The system integrates low-level hardware display drivers with high-level graphics libraries to facilitate the development of sophisticated visual interfaces, ranging from simple monochrome text displays to complex touch-enabled color GUIs.
At its core, the architecture separates physical display hardware management from logical frame buffer operations and UI component rendering. This separation allows for modular development where a single UI implementation using LVGL can be ported across different display hardware by simply swapping the underlying Zephyr display driver. The module is built with safety and security in mind, adhering to the project's broader Safety Overview and Security Overview principles.
Architecture and Data Flow
The display subsystem follows a layered model consistent with Zephyr's modular design. Data flows from high-level UI components through a graphics library (LVGL) or character frame buffer (CFB), down to the device-specific display driver.
UI Stack Layers
| Layer | Component | Function |
|---|---|---|
| Application UI | LVGL Widgets / Custom Code | Defines UI layout, buttons, and animations. |
| Graphics Engine | LVGL / Character Frame Buffer | Handles rendering logic and logical buffer management. |
| Subsystem API | Display API | Provides a unified interface for writing buffers to hardware. |
| Hardware Driver | Dummy, LCD, or E-Paper Drivers | Communicates directly with hardware (SPI, I2C, Parallel). |
Sources: doc/safety/safety_overview.rst:155-165, modules/lvgl/lvgl.c, subsys/display/cfb.c
Logical Data Flow
The following diagram illustrates how pixels are processed from the library level to the physical hardware.
The diagram shows the transition from logical UI libraries to hardware-specific driver implementations via the unified Display API.
Sources: modules/lvgl/lvgl.c:1-50, subsys/display/cfb.c:10-40, drivers/display/display_dummy.c:15-30
Display Driver Model
Display drivers in Zephyr are implemented as device drivers that export a standard API. This allows the OS to interact with a wide variety of hardware (OLED, TFT, E-Ink) using common function calls.
Dummy Display Driver
A dummy display driver is often used for testing or as a template. It implements the basic API without physical hardware interactions.
dummy_display_write: Accepts a buffer and coordinates to simulate writing pixels.dummy_display_read: Returns an error or stubbed data, as reading from displays is often unsupported.dummy_display_get_capabilities: Returns static information such as resolution and color formats.
Sources: drivers/display/display_dummy.c:22, drivers/display/display_dummy.c:45, drivers/display/display_dummy.c:60
Capabilities and Configuration
Drivers must define their capabilities to allow upper layers like LVGL to initialize correctly. This includes:
- Resolution: X and Y dimensions in pixels.
- Color Formats: Supported formats like RGB565, ARGB8888, or monochrome.
- Orientation: Supported screen rotations.
Sources: drivers/display/display_dummy.c:65-80
Character Frame Buffer (CFB)
The Character Frame Buffer (CFB) is a specialized subsystem for simpler displays, typically monochrome or low-color OLEDs/LCDs. It focuses on rendering fonts and simple geometric shapes into a logical buffer before pushing them to the display driver.
Key Functions
cfb_framebuffer_init: Initializes the logical buffer based on the display device capabilities.cfb_print: Renders text at specific coordinates using configured fonts.cfb_framebuffer_finalize: Compresses or formats the buffer as required by the hardware.cfb_framebuffer_flush: Calls the underlying display driver'swritefunction to update the screen.
Sources: subsys/display/cfb.c:50-100
LVGL Integration
LVGL is the primary high-level graphics library integrated into the project. The Zephyr module for LVGL manages the lifecycle of the library, including initialization and the recurring task handler.
Initialization Sequence
The sequence shows the internal initialization of LVGL and its dependency on kernel timers for task processing.
Sources: modules/lvgl/lvgl.c:80-120
Task Management
LVGL requires periodic execution to handle animations, input, and rendering. The Zephyr implementation typically uses a dedicated thread or a kernel timer to call lv_task_handler() at regular intervals (e.g., 5ms or 10ms).
Sources: modules/lvgl/lvgl.c:150-165
Safety and Quality Standards
Display drivers and UI components fall under the project's safety and quality goals. To be considered an auditable code base, display-related modules must meet specific criteria.
- Layered Architecture: Display drivers are strictly separated from UI logic to ensure modularity.
- Encapsulation: Components are encapsulated to prevent repercussions on other system functions.
- Coding Guidelines: Code must follow Stage II/III enforcement to prevent systematic errors.
- Test Coverage: Safety-relevant paths in display drivers require high structural test coverage (Statements and Branches).
Sources: doc/safety/safety_overview.rst:110-130, doc/safety/safety_overview.rst:155-175
Conclusion
The Display Driver and LVGL UI system provides a robust framework for visual feedback on embedded devices. By leveraging Zephyr's unified driver model and integrating powerful libraries like LVGL and CFB, the project enables developers to build scalable interfaces. The emphasis on layered architecture and modularity ensures that these components remain maintainable and suitable for safety-critical and high-security applications.