LVGL Port (rm_lvgl_port)

Functions
fsp_err_t	RM_LVGL_PORT_Open (rm_lvgl_port_instance_ctrl_t *const p_instance_ctrl, rm_lvgl_port_cfg_t const *const p_cfg)

Detailed Description

LVGL graphics library port for RA MCUs.

Overview

The LVGL RA Port module provides the configuration necessary for use of the LVGL graphics library on RA products. The port provides integration for GLCDC into the LVGL display system, a time source for LVGL timer logic, and optional integration with FreeRTOS.

Note

This port layer primarily enables hardware acceleration and background handling of many display operations and does not contain code intended to be directly called by the user. Please consult the LVGL Project Documentation for details on how to use LVGL in your project.

Hardware Acceleration

Hardware acceleration is optionally provided by DRW using a lightly modified fork of the upstream driver provided by the LVGL project. Most rendering operations are supported.

---

Configuration

Build Time Configurations for lvgl

The following build time configurations are defined in fsp_cfg/lvgl/lvgl/lv_conf.h:

Configuration	Options	Default	Description
General
Custom lv_conf.h	Manual Entry		Add a path to your custom lv_conf.h file. It can be used to override some or all of the configurations defined here, and to define additional configurations.
LVGL
LVGL > Display
LV_COLOR_DEPTH	Value must equal 16 or 32.	16	Color depth. 16 or 32 supported.
LVGL > Memory
LV_MEM_SIZE	Value must be an integer multiple of 1024 between 0x800 and 0xFFFFFFFF.	0x10000	Size of the memory available for `lv_malloc()` in bytes.
LV_DRAW_LAYER_SIMPLE_BUF_SIZE	Value must be an integer multiple of 1024 between 0x400 and 0xFFFFFFFF.	0x6000	Buffer size for simple layer chunks.
LV_DRAW_LAYER_MAX_MEMORY	Value must be an integer.	0	Limit the max allocated memory for simple and transformed layers. 0 for no limit. Otherwise, should be greater than or equal to LV_DRAW_LAYER_SIMPLE_BUF_SIZE. If transformed layers are used, it should be large enough for the largest widget (width x height x 4 area).
LV_DRAW_THREAD_STACK_SIZE	Value must be an integer multiple of 1024 between 0x400 and 0xFFFFFFFF.	0x2000	Stack size of the drawing thread in bytes. Only used when FreeRTOS integration is used.
LVGL > OS Integration
LV_USE_OS	LV_OS_NONE LV_OS_FREERTOS	LV_OS_FREERTOS	Select LVGL RTOS integration.
LV_DRAW_THREAD_PRIO	LV_THREAD_PRIO_LOWEST LV_THREAD_PRIO_LOW LV_THREAD_PRIO_MID LV_THREAD_PRIO_HIGH LV_THREAD_PRIO_HIGHEST	LV_THREAD_PRIO_HIGH	Thread priority of the drawing task.
LVGL > Software Rendering
LV_DRAW_SW_SUPPORT_RGB565	Enabled Disabled	Enabled	Enable software rendering support for the specified color format. Disable to reduce code size. Some formats may be used internally for some features.
LV_DRAW_SW_SUPPORT_RGB565_SWAPPED	Enabled Disabled	Enabled	Enable software rendering support for the specified color format. Disable to reduce code size. Some formats may be used internally for some features.
LV_DRAW_SW_SUPPORT_RGB565A8	Enabled Disabled	Enabled	Enable software rendering support for the specified color format. Disable to reduce code size. Some formats may be used internally for some features.
LV_DRAW_SW_SUPPORT_RGB888	Enabled Disabled	Enabled	Enable software rendering support for the specified color format. Disable to reduce code size. Some formats may be used internally for some features.
LV_DRAW_SW_SUPPORT_XRGB8888	Enabled Disabled	Enabled	Enable software rendering support for the specified color format. Disable to reduce code size. Some formats may be used internally for some features.
LV_DRAW_SW_SUPPORT_ARGB8888	Enabled Disabled	Enabled	Enable software rendering support for the specified color format. Disable to reduce code size. Some formats may be used internally for some features.
LV_DRAW_SW_SUPPORT_ARGB8888_PREMULTIPLIED	Enabled Disabled	Enabled	Enable software rendering support for the specified color format. Disable to reduce code size. Some formats may be used internally for some features.
LV_DRAW_SW_SUPPORT_L8	Enabled Disabled	Enabled	Enable software rendering support for the specified color format. Disable to reduce code size. Some formats may be used internally for some features.
LV_DRAW_SW_SUPPORT_AL88	Enabled Disabled	Enabled	Enable software rendering support for the specified color format. Disable to reduce code size. Some formats may be used internally for some features.
LV_DRAW_SW_SUPPORT_A8	Enabled Disabled	Enabled	Enable software rendering support for the specified color format. Disable to reduce code size. Some formats may be used internally for some features.
LV_DRAW_SW_SUPPORT_I1	Enabled Disabled	Enabled	Enable software rendering support for the specified color format. Disable to reduce code size. Some formats may be used internally for some features.
LVGL > Hardware Rendering
LV_USE_DRAW_DAVE2D	Enabled Disabled	Enabled	Enable built-in DRW Engine support.
LVGL > Debug
LV_ASSERT_HANDLER_INCLUDE	Manual Entry	<stdint.h>	Header file to include to support LV_ASSERT_HANDLER macro.
LV_ASSERT_HANDLER	Manual Entry		Macro to execute when an LV_ASSERT occurs.
LVGL > Widgets
LV_USE_OBJ_NAME	Enabled Disabled	Disabled	Enable support for widget names.
LVGL > Input Devices
LV_USE_GESTURE_RECOGNITION	Enabled Disabled	Disabled	Enable support for multi-touch gesture recognition. Requires floating point support.
LV_USE_IME_PINYIN	Enabled Disabled	Disabled	Enable Pinyin input method.
LV_IME_PINYIN_USE_DEFAULT_DICT	Enabled Disabled	Enabled	Use default thesaurus.
LV_IME_PINYIN_CAND_TEXT_NUM	Value must be positive.	6	Maximum number of displayed candidate panels. Adjust according to screen size.
LV_IME_PINYIN_USE_K9_MODE	Enabled Disabled	Enabled	Use nine key (K9) input.
LV_IME_PINYIN_K9_CAND_TEXT_NUM	Value must be positive.	3	Maximum number of displayed candidate panels in K9 mode. Adjust according to screen size.
LVGL > Fonts
LVGL > Fonts > Montserrat
LV_FONT_MONTSERRAT_8	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 8.
LV_FONT_MONTSERRAT_10	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 10.
LV_FONT_MONTSERRAT_12	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 12.
LV_FONT_MONTSERRAT_14	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 14.
LV_FONT_MONTSERRAT_16	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 16.
LV_FONT_MONTSERRAT_18	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 18.
LV_FONT_MONTSERRAT_20	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 20.
LV_FONT_MONTSERRAT_22	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 22.
LV_FONT_MONTSERRAT_24	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 24.
LV_FONT_MONTSERRAT_26	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 26.
LV_FONT_MONTSERRAT_28	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 28.
LV_FONT_MONTSERRAT_30	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 30.
LV_FONT_MONTSERRAT_32	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 32.
LV_FONT_MONTSERRAT_34	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 34.
LV_FONT_MONTSERRAT_36	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 36.
LV_FONT_MONTSERRAT_38	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 38.
LV_FONT_MONTSERRAT_40	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 40.
LV_FONT_MONTSERRAT_42	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 42.
LV_FONT_MONTSERRAT_44	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 44.
LV_FONT_MONTSERRAT_46	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 46.
LV_FONT_MONTSERRAT_48	Enabled Disabled	Enabled	Enable built-in font (FontAwesome5, Montserrat) size 48.
LVGL > Fonts > DejaVu
LV_FONT_DEJAVU_16_PERSIAN_HEBREW	Enabled Disabled	Enabled	Enable built-in font DejaVu (Arabic, Hebrew, Persian) size 16.
LVGL > Fonts > SourceHanSansSC
LV_FONT_SOURCE_HAN_SANS_SC_14_CJK	Enabled Disabled	Enabled	Enable built-in font SourceHanSansSC size 14.
LV_FONT_SOURCE_HAN_SANS_SC_16_CJK	Enabled Disabled	Enabled	Enable built-in font SourceHanSansSC size 16.
LVGL > Fonts > Unscii
LV_FONT_UNSCII_8	Enabled Disabled	Enabled	Enable built-in font unscii-8 size 8.
LV_FONT_UNSCII_16	Enabled Disabled	Enabled	Enable built-in font unscii-8 size 16.
LV_FONT_DEFAULT	Name must be a valid C symbol.	lv_font_montserrat_14	Set a default font for LVGL. Required.
LV_USE_FONT_PLACEHOLDER	Enabled Disabled	Enabled	Draw a placeholder when a glyph is not found.
LV_USE_BIDI	Enabled Disabled	Disabled	Enable bidirectional text.
LV_USE_ARABIC_PERSIAN_CHARS	Enabled Disabled	Disabled	Enable Arabic and Persian language processing.
LV_USE_FONT_MANAGER	Enabled Disabled	Disabled	Enable the font manager.
LV_FONT_MANAGER_NAME_MAX_LEN	Value must be positive.	32	Maximum font name length when font manager is enabled.

Build Time Configurations for rm_lvgl_port

The following build time configurations are defined in fsp_cfg/middleware/rm_lvgl_port_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.
Provide Tick Callback	Enabled Disabled	Enabled	Enable the LVGL port driver to provide a tick callback to LVGL.

Configurations for Graphics > LVGL Port (rm_lvgl_port)

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_rm_lvgl_port0	Module name.
Target Display Layer	Graphics Layer 1 Graphics Layer 2	Graphics Layer 1	Specify which graphics screen to inherit the buffer and display dimensions from.
Callback Function	Must be a valid C symbol	NULL	If a callback function is provided it will be called when Display events occur.

Hardware Configuration

No clocks or pins are directly required by this module. Please consult the GLCDC Usage Guide for its requirements here: Graphics LCD (r_glcdc)

LVGL Configuration

LVGL is configured via the use of a configuration header. The port layer provides configuration options within e2 Studio for commonly changed LVGL settings and autogenerates the required header files. It is also possible to provide a custom LVGL configuration header which overrides the LVGL configuration options set in e2 Studio, or configures options that are not exposed in the port layer in e2 Studio.

---

Usage Notes

Getting Started

To get started with LVGL in an RA project the following must be performed:

1. In e2 studio, open the RA Configuration editor for your project
2. Add LVGL to your project in the Stacks view by clicking New Stack -> Graphics -> LVGL
   • If using FreeRTOS, first create a new thread and add the LVGL stack to it
3. Set the properties for the GLCDC module to match the timing and memory requirements of your display panel
4. Ensure interrupts on all modules are enabled:
   • GLCDC Vertical Position (GLCDC_VPOS) Interrupt
   • DRW Interrupt (if applicable)
5. Confirm stack size and global heap size are configured as needed
   • If using FreeRTOS, it is suggested to add the Heap_4 stack to provide memory allocation to DRW
   • Stack size must be adequate for the thread executing the LVGL timer handler loop
   • Stack size is configured per thread if FreeRTOS is used
   • Final heap and stack usage must be characterized
6. Ensure the configuration options for LVGL are set as necessary for your application
7. Confirm LVGL heap size is configured as needed
   • Final LVGL heap usage must be characterized
8. Confirm other LVGL memory parameters are configured as needed
   • Final memory usage for miscellaneous memory parameters must be characterized
9. Resolve any remaining constraints
10. Click Generate Project Content to save and commit configuration changes

At this point the project is now ready to build with LVGL. Please refer to the LVGL Project Documentation for details on how to use LVGL in your project, as well as LVGL demo and example code.

Demos and Examples

The LVGL packed with FSP also includes the demos and examples directories that are in the LVGL project. To allow the demos to be included and built in a user project:

1. Create a custom LVGL configuration header, for example lv_conf_custom.h
2. Specify the header file name in the General|Custom lv_conf.h LVGL stack configuration property
3. Set the LV_BUILD_DEMOS macro to 1 in the custom header, to override the value set in the generated lv_conf.h
4. Set the desired LV_USE_DEMO_* macro to 1 in the the custom header, to enable the desired demo
5. Call the desired demo function prior to lv_timer_handler() to set up the demo

Including and building the examples in a user project are the same steps, but set the LV_BUILD_EXAMPLES macro to 1 in the custom header instead. No LV_USE_ macros should be required for the examples.

Note

Not all upstream demos and examples material are available, so some demos or examples may not build or execute.

Libraries

The LVGL packed with FSP also includes the libs directory that is in the LVGL project. Only bin_decoder is packed as a mandatory library. The source for the remaining libraries is omitted.

Note

This means that some third party libraries included with upstream LVGL are unavailable. The excluded libraries are mostly inapplicable to an RA embedded context.

Multi-thread Support

LVGL is not a thread safe library. Please refer to Tasks and threads for information on how to use LVGL in a multi-thread environment.

Note

This includes both bare metal and FreeRTOS projects. RTOS support is optionally configured depending on whether FreeRTOS is used in the project.

Limitations

Developers should be aware of the following limitations when using LVGL with FSP:

• Compilers may produce different results at this time (v9.3.0). AC6 is known to produce different software rendering output when blending certain image formats with a 32-bit color depth. LLVM is known to create artifacts with LVGL image decoding and blending.
• The DRW upstream driver does not support all LVGL rendering features. Some unsupported features are horizontal gradients, dashed lines, and blitting of certain image formats. In some cases, the LVGL software renderer will act as a fallback renderer, such as when an unsupported image format is used.

  ---

Examples

Basic Example

This is a basic example demonstrating the initialization of LVGL and the port layer within a FreeRTOS thread entry function, then servicing LVGL timer logic in a loop.

Note

The port layer manages the GLCDC submodule internally, while the LVGL project manages the DRW submodule; they do not need to be opened directly.

void lvgl_thread_entry (void * pvParameters)
{
    FSP_PARAMETER_NOT_USED(pvParameters);
    fsp_err_t error;

    /* Initialize LVGL. */
    lv_init();

    /* TODO: Perform any initialization necessary for the physical display. */


    /* Initialize the LVGL port driver. */
    error = RM_LVGL_PORT_Open(&g_lvgl_port_ctrl, &g_lvgl_port_cfg);

    /* TODO: Handle fsp_err_t return values as required. */
    (void) error;


    /* TODO: Create an input device using LVGL. */

    /* TODO: Create a user defined UI using LVGL widgets. */

    /* For example, add a label to the LVGL active screen on the default display. */

    lv_obj_t * active_screen = lv_screen_active();
    lv_obj_set_style_text_color(active_screen, lv_color_black(), 0);
    lv_obj_set_style_bg_color(active_screen, lv_color_white(), 0);

    lv_obj_t * label_object = lv_label_create(active_screen);
    lv_label_set_text(label_object, "Hello World!");

    /* Call lv_timer_handler() to process LVGL timer tasks, which includes display refresh. */
    while (1)
    {
        lv_timer_handler();
        vTaskDelay(1);
    }
}

Note

For further example code please consult the LVGL Project Documentation.

Data Structures
struct	rm_lvgl_port_callback_args_t
struct	rm_lvgl_port_cfg_t
struct	rm_lvgl_port_instance_ctrl_t

Enumerations
enum	rm_lvgl_port_device_t
enum	rm_lvgl_port_event_t

---

Data Structure Documentation

rm_lvgl_port_callback_args_t

struct rm_lvgl_port_callback_args_t

Callback arguments for the FSP LVGL Port

Data Fields
rm_lvgl_port_device_t	device	Device code.
rm_lvgl_port_event_t	event	Event code of the low level hardware.
uint32_t	error	Error code if RM_LVGL_PORT_EVENT_ERROR.

rm_lvgl_port_cfg_t

struct rm_lvgl_port_cfg_t

Configuration structure for the FSP LVGL Port

rm_lvgl_port_instance_ctrl_t

struct rm_lvgl_port_instance_ctrl_t

Instance control block for LVGL Port

Enumeration Type Documentation

rm_lvgl_port_device_t

enum rm_lvgl_port_device_t

Low level device code for the LVGL Port

Enumerator
RM_LVGL_PORT_DEVICE_NONE	Non hardware.
RM_LVGL_PORT_DEVICE_DISPLAY	Display device.

rm_lvgl_port_event_t

enum rm_lvgl_port_event_t

Display event codes

Enumerator
RM_LVGL_PORT_EVENT_DISPLAY_VPOS	Display interface VPOS.
RM_LVGL_PORT_EVENT_UNDERFLOW	Display interface underflow.

Function Documentation

RM_LVGL_PORT_Open()

fsp_err_t RM_LVGL_PORT_Open	(	rm_lvgl_port_instance_ctrl_t *const	p_instance_ctrl,
		rm_lvgl_port_cfg_t const *const	p_cfg
	)

Open the LVGL port driver module.

Example:

    /* Initialize the LVGL port driver. */
    error = RM_LVGL_PORT_Open(&g_lvgl_port_ctrl, &g_lvgl_port_cfg);

    /* TODO: Handle fsp_err_t return values as required. */
    (void) error;

Note

This function should be called after the LVGL function lv_init() has been called.

Return values

FSP_SUCCESS	LVGL port successfully opened.
FSP_ERR_OUT_OF_MEMORY	Internal call to lv_display_create() failed to allocate memory for a display.

See Common_Error_Codes for other possible return codes. This function calls R_GLCDC_Open(), R_GLCDC_Start(), and R_GLCDC_BufferChange().