LVGL 9.2 port (draft — tcan v2.0 migration)

[mLupine]

LVGL 9.2 port

This is a draft PR porting lv_binding_rust from LVGL 8.x to LVGL 9.2.x, opened as a conversation-starter rather than a merge-ready submission.

Motivation

I’m rewriting an ESP-IDF v6 firmware stack (originally Arduino-era C++) in Rust, and need LVGL 9.2 Rust bindings because esp_lvgl_port 2.3 (shipping with IDF v6) targets LVGL 9.x exclusively.

Upstream main targets LVGL 8.x. Issue #195 has been open since Feb 2025 asking for LVGL 9 support, with zero PRs in flight. This PR establishes a minimum-viable 9.x surface so downstream projects can unblock; broader API restoration (embedded-graphics integration, lv_drivers SDL/Linux backends, the full widget catalog, the style builder) is explicit follow-up work.

Branch

• Fork: mLupine/lv_binding_rust-fork@mLupine-lvgl-9
• Branched from upstream d83b3740 (HEAD at time of fork).

Changes summary

Three commits (full messages on the branch):

1. be56b12 — vendor LVGL 9.2.2 + lvgl-sys bindgen against 9.x

   • Replace the LVGL 8.3.7 git submodule (vendor/lvgl, vendor/lv_drivers) with a vendored drop of LVGL v9.2.2 under lvgl-sys/vendor/lvgl-9.2/.
   • Add lvgl-sys/vendor/include-9.2/lv_conf.h (template-derived, LV_USE_SNAPSHOT=1).
   • Rewrite lvgl-sys/build.rs for the LVGL 9 source layout (cc compiles every .c under vendor/lvgl-9.2/src; bindgen runs against shims/lvgl_sys.h with allowlists lv_.* / LV_.* / _LV_COLOR_.*).
   • Update the LVGL-color shim for LVGL 9's native-RGB888 lv_color_t ({blue,green,red} field accessors; _LV_COLOR_GET_A returns 0xFF since alpha now lives in lv_color32_t).
   • Switch the lvgl-sys sanity test from lv_disp_get_hor_res (LVGL 8) to lv_display_get_horizontal_resolution (LVGL 9).
   • Bump both crate versions to 0.6.2-mLupine-lvgl-9.

2. 4861b1b — port lvgl crate safe wrapper to LVGL 9.2 (minimum-viable)

   • Replace the 4083-LOC LVGL 8 lvgl/src/ tree with a slim hand-authored 9.x surface scoped to what downstream lupin-display needs:
     • display.rs — Display::create + Display::from_raw for interop with esp_lvgl_port::lvgl_port_add_disp returns; LVGL-9 byte-buffer flush-callback adapter.
     • color.rs — Color + ColorFormat enum mapping lv_color_format_t.
     • obj.rs, screen.rs — thin handles.
     • image_dsc.rs — alias over lv_image_dsc_t (renamed from LVGL 8's lv_img_dsc_t).
     • widgets/{label,image/mod}.rs.
     • snapshot.rs — lv_snapshot_take + lv_draw_buf_destroy (for RGB565 capture over UART).
   • build.rs becomes a no-op — LVGL 8 lvgl-codegen widget pipeline is unused in this PR (regenerating against LVGL 9 widget signatures is separate follow-up work).
   • Drop embedded-graphics / cstr_core / bitflags / paste / ctor and the LVGL 8 example matrix from Cargo.toml.

3. 2ea8ccd — teach lvgl-sys/build.rs to find xtensa newlib headers

   • bindgen invokes a separate clang with -target xtensa-esp32s3-espidf that fails on <inttypes.h> because no sysroot is supplied; resolved by shelling out to xtensa-esp-elf-gcc -print-sysroot at build time and adding -I<sysroot>/include to bindgen's clang args (silently skipped when the xtensa toolchain isn't on PATH).

Verification

• Host build: cargo build -p lvgl --target aarch64-apple-darwin → Finished.
• Cross-compile: cargo +esp build -p lvgl --target xtensa-esp32s3-espidf on ESP-IDF v6 → Finished (one harmless improper_ctypes warning on a varargs va_list field).

Status

This PR is draft pending (any of these are welcome as conversation points, not blockers):

• API-shape review from lv_binding_rust maintainers — I'd prefer to converge on upstream's preferred shape for the Display::from_raw_display / flush-callback / color-format-awareness seams rather than upstream ad-hoc choices.
• Widget catalog restoration — the slim surface covers only what my project exercises today (label + image + snapshot + base Display). Bar, arc, slider, table, meter, keyboard, the style builder, and the embedded_graphics + lv_drivers integrations are deliberately not included.
• Test-suite port — LVGL 8 tests hard-code layouts that no longer exist under LVGL 9.
• input_device family — LVGL 9 removed lv_indev_drv_t; the input_device module is not ported.

Happy to split this into smaller PRs if that's easier to review (vendor-drop + lvgl-sys as one, safe wrapper as another, build.rs xtensa fix as a third).

Un-forking plan

Once this (or an equivalent) upstream PR merges and a released lvgl = "…" crate tracks LVGL 9.2, downstream tcan-rust reverts its .deps/lv_binding_rust submodule and consumes the crate directly.

---

Summary by cubic

Ports the Rust bindings to LVGL 9.2.2 and ships a minimal lvgl 9.x API (display, color, label, image, snapshot) to unblock ESP‑IDF v6 / esp_lvgl_port users.

• New Features

  • Vendored LVGL 9.2.2 under lvgl-sys/vendor/lvgl-9.2/; updated lvgl-sys build (compile new src tree, bindgen allowlists) and color shims; tests use lv_display_get_*_resolution.
  • Minimal lvgl 9 API: Display::{create, from_raw}, byte-buffer flush adapter, Color/ColorFormat mapped to lv_color_format_t, widgets Label and Image, and Snapshot; dropped 8.x codegen, examples, and deps.
  • Cross-compile QoL: auto-detect xtensa newlib sysroot for bindgen; added inner .cargo/config.toml so local builds default to host.

• Migration

  • Flush callbacks now receive raw bytes; interpret via the per-display color format. lv_color_t is RGB888 (BGR fields); alpha lives in lv_color32_t.
  • Use lv_display_* APIs (e.g., lv_display_get_horizontal_resolution). The 8.x lv_indev_drv_t path is not ported.
  • Not included in this PR: embedded-graphics, lv_drivers backends, and the full widget/style builder surface. Only Label, Image, and Snapshot are available today.

^{Written for commit 2ea8ccd. Summary will update on new commits.}