diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..96484a2fd4 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,63 @@ +# 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/`) + +## 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___` 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 +- `` 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: `(): ` — 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 diff --git a/.github/instructions/c-code.instructions.md b/.github/instructions/c-code.instructions.md new file mode 100644 index 0000000000..433e576e04 --- /dev/null +++ b/.github/instructions/c-code.instructions.md @@ -0,0 +1,43 @@ +--- +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_valid()` in internal callbacks — it walks the entire object tree +- 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__H` / `#define` / `#endif` +- Feature-gated files: keep `#if LV_USE_` 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