lvgl/.github/instructions/c-code.instructions.md

applyTo

applyTo
src/**/*.c,src/**/*.h

LVGL C Source Review Rules

Memory Safety

• Every lv_malloc / lv_realloc must have a NULL check immediately after
• Every allocation must have a matching lv_free on all exit paths (including error paths)
• lv_free(NULL) is safe — don't add redundant NULL checks before it
• Pointer parameters: NULL-check before dereference when caller could reasonably pass NULL
• Array access must be bounds-checked

Error Handling

• Functions returning lv_result_t must be checked by callers
• Error paths must clean up all allocated resources before returning
• Graceful runtime fallback is preferred over assert for recoverable failures (e.g. cache allocation failure should degrade, not crash)
• Add LV_LOG_WARN for unexpected but recoverable conditions
• Add LV_LOG_ERROR for conditions that indicate a bug

Performance

• No heap allocation in hot paths (draw loops, event handlers, timer callbacks)
• Prefer stack allocation for small temporary buffers
• Avoid lv_obj_is_in_widget_tree() in internal callbacks — it walks up the parent chain and scans every display's screen list
• Cache-friendly access: sequential over random
• Struct member ordering: pointers first, then int32_t, then smaller types/bitfields — minimizes padding

Portability

• No platform headers without #if guards
• No compiler extensions without fallback
• No float/double in core code unless behind LV_USE_FLOAT
• Use LV_ATTRIBUTE_* macros for alignment/section placement
• Use "%" LV_PRId32 for int32_t format strings, not "%d"

Include Structure

• .h files: #ifndef LV_<MODULE>_H / #define / #endif
• Feature-gated files: keep #if LV_USE_<FEATURE> near the top and the matching #endif at the bottom; necessary includes (module headers, private headers) may appear before the feature guard
• Never include test headers in production source files