Common Issues and Troubleshooting

Frame rate drops after opening and returning from an app

Symptoms

When scrolling the app list to test frame rate, the FPS after opening a JS app and returning to the list is noticeably lower than testing directly after system boot. The FPS drop scales with the number of suspended apps (~5-10 FPS per suspended app).

Cause

LV_USE_ASSERT_MEM_INTEGRITY is set to 1 in lv_conf.h.

When enabled, LVGL calls lv_mem_test() after every timer callback (lv_timer.c), object-tree operation (lv_obj_tree.c), and draw operation (lv_draw_rect.c, lv_draw_label.c). lv_mem_test() walks the entire TLSF memory pool checking every block header. With the built-in TLSF allocator (LV_STDLIB_BUILTIN), each suspended app (Recents) adds more allocated blocks → integrity check time grows linearly → FPS drops linearly.

This can be confirmed with macOS Instruments (Time Profiler): samples will show lv_tlsf_check / integrity_walker / block_is_free dominating the frame budget.

Solution

Set LV_USE_ASSERT_MEM_INTEGRITY to 0 in lv_conf.h:

#define LV_USE_ASSERT_MEM_INTEGRITY 0

This option is useful for catching heap corruption during development, but must be disabled when doing any frame-rate, scrolling, or animation performance testing. The other asserts (LV_USE_ASSERT_NULL, LV_USE_ASSERT_MALLOC) are O(1) checks and safe to leave on.