lvgl/.github/copilot-instructions.md

LVGL Code Review Instructions

LVGL is an embedded C99 graphics library for MCUs, MPUs, and simulators. Code must be portable, memory-efficient, and bare-metal safe.

Critical Issues (always flag)

• NULL dereference: every lv_malloc/lv_realloc result must be checked
• Buffer overflow or out-of-bounds array access
• Memory leak: every lv_malloc needs matching lv_free on all exit paths
• Use-after-free, uninitialized variable use
• Integer overflow in size/coordinate calculations
• Missing #if LV_USE_xxx / #endif guards for optional features
• Global variables not in lv_global_t — must use LV_GLOBAL_DEFAULT()
• Test headers included in production source (#include "lv_test_..." in src/)
• Missing LV_CHECK_ARG(...) on arguments of public API functions
• Missing LV_CHECK_OBJ(obj, cls, action) for lv_obj_t */const lv_obj_t * parameters in public API functions
• LV_ASSERT* for public API function arguments. Instead the user must use LV_CHECK_ARG or LV_CHECK_OBJ based on the points above

Argument Checking Contract

• Public API functions use LV_CHECK_ARG/LV_CHECK_OBJ as the sole argument-safety mechanism
• When LV_USE_CHECK_ARG=0 checks compile out by design. Do not flag missing unconditional NULL guards; passing invalid args with checks disabled is caller undefined behavior, not a library defect
• LV_ASSERT* must not be used for this purpose

Embedded Performance (flag in hot paths)

• No heap allocation in draw loops, event handlers, timer callbacks
• Avoid lv_obj_is_valid() in internal callbacks — walks entire object tree
• lv_free(NULL) is safe — no redundant NULL check before it

Naming & Style

• lv_<module>_<action>_<subject> for public API
• ALL_CAPS for enums/defines; _t suffix for typedefs
• 4 spaces, no tabs; function brace on new line; if/for brace on same line
• <stdint.h> types; C files use block comments /* */ only (no //), C++ files may use //; "%" LV_PRId32 for format strings
• File-scope variables must be static; no globals outside lv_global_t

Code Organization

• Extract helpers when functions exceed ~50 lines, but don't over-engineer single-use helpers
• Eliminate code duplication across branches
• Struct layout: pointers first, then int32, then small types/bitfields (minimize padding)
• New files follow src/misc/lv_templ.c section template
• #if LV_USE_xxx near top, #endif /* LV_USE_xxx */ at bottom

Memory & Error Patterns

• Prefer graceful degradation over assert for recoverable failures (e.g. cache alloc fail → log + disable, not crash)
• LV_LOG_WARN for unexpected recoverable conditions; LV_LOG_ERROR for bugs

GPU / Draw Units

• All vg_lite_* calls: check with LV_VG_LITE_CHECK_ERROR
• Use current API names (vg_lite_set_path_type not deprecated variants)
• GL state: save and restore (scissor, framebuffer binding, clear color)
• #if LV_USE_DRAW_* guards required

PR Requirements

• Commit: <type>(<scope>): <subject> — imperative, lowercase, no period, max 90 chars
• Types with source code changes: fix, feat, refactor, arch, perf, style, test
• Types without source code changes: chore, ci, docs, build
• Exception: inline source documentation (Doxygen) uses docs even though it lives in source files
• CI analyzes and reports patch coverage on new coverable lines
• New features need tests; bug fixes need regression tests when feasible
• New features and API changes should include examples in examples/
• If lv_conf_template.h was modified, check that lv_conf_internal_gen.py was run and Kconfig updated
• Code must be formatted with scripts/code-format.py (astyle) — flag obvious style violations
• Doxygen /** */ with @param/@return for all public functions in .h files
• Comments explain why, not what