fw/services/compositor: make freeze wait for in-flight display updates

compositor_freeze() only raised a flag that the KernelMain render
paths consult. It was called from the BT task by the screenshot
endpoint, which then copied the first framebuffer chunk immediately,
so a display update that had already been kicked off could still be
in flight while the screenshot read the framebuffer.

On sf32lb boards (obelix, getafix) the JDI driver converts the dirty
rows of the compositor framebuffer in-place from 2-2-2 to 3-3-2 for
the LCDC and only converts them back after the DMA completes, from a
KernelMain callback. Screenshots sampling those rows in that window
carry 3-3-2 pixels reinterpreted as GColor8: orange (0xF4) reads
back as GColorIslamicGreen (0xC8), which is the green status bar in
the report.

Turn compositor_freeze() into an asynchronous request: the freeze
takes effect on KernelMain and a callback fires there once no display
update is in progress, either straight away or from the display
update complete handler. The screenshot starts streaming from that
callback on the system task, and the ALS console command drops its
hand-rolled spin on compositor_display_update_in_progress(). Add unit
tests for both the idle and the update-in-flight cases.

Fixes FIRM-4357

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Gerard Marull-Paretas <gerard@teslabs.com>

Author: gmarull

include/pbl/services/compositor/compositor.h

@@ -116,8 +116,13 @@ void compositor_set_modal_transition_offset(GPoint modal_offset);
 //! Stops an existing transition in its tracks.
 void compositor_transition_cancel(void);
 
-//! Don't allow new frames to be pushed to the compostor from either the app or the modal.
-void compositor_freeze(void);
+typedef void (*CompositorFrozenCallback)(void *data);
+
+//! Don't allow new frames to be pushed to the compositor from either the app or the modal.
+//! Callable from any task. \a callback runs on KernelMain once the freeze is in effect and no
+//! display update is in flight, at which point the framebuffer is stable until
+//! \ref compositor_unfreeze. Only one freeze may be outstanding at a time.
+void compositor_freeze(CompositorFrozenCallback callback, void *data);
 
 //! Resuming allowing new frames to be pushed to the compositor, undoes the effects of
 //! compositor_freeze.

src/fw/services/compositor/compositor.c

@@ -77,6 +77,8 @@ static DeferredRender s_deferred_render;
 static CompositorTransitionState s_animation_state;
 
 static bool s_framebuffer_frozen;
+static CompositorFrozenCallback s_frozen_callback;
+static void *s_frozen_callback_data;
 
 //! Animation .update function for the AnimationImplementation we use to drive our transitions.
 //! Wraps the .update function of the current CompositorTransition.
@@ -101,6 +103,8 @@ void compositor_init(void) {
   s_animation_state = (CompositorTransitionState) { 0 };
 
   s_framebuffer_frozen = false;
+  s_frozen_callback = NULL;
+  s_frozen_callback_data = NULL;
 }
 
 // Helper functions to make implementing transitions easier
@@ -173,6 +177,15 @@ void compositor_render_modal(void) {
 // Compositor implementation
 ///////////////////////////////////////////////////////////
 
+static void prv_notify_frozen(void) {
+  if (!s_frozen_callback || compositor_display_update_in_progress()) {
+    return;
+  }
+  CompositorFrozenCallback callback = s_frozen_callback;
+  s_frozen_callback = NULL;
+  callback(s_frozen_callback_data);
+}
+
 T_STATIC void prv_handle_display_update_complete(void) {
   if (s_deferred_render.transition_complete.pending) {
     s_deferred_render.transition_complete.pending = false;
@@ -193,6 +206,7 @@ T_STATIC void prv_handle_display_update_complete(void) {
     s_deferred_render.app.pending = false;
     compositor_app_render_ready();
   }
+  prv_notify_frozen();
 }
 
 static void prv_compositor_flush(void) {
@@ -481,8 +495,16 @@ void compositor_transition_cancel(void) {
   }
 }
 
-void compositor_freeze(void) {
+static void prv_compositor_freeze_cb(void *ignored) {
   s_framebuffer_frozen = true;
+  prv_notify_frozen();
+}
+
+void compositor_freeze(CompositorFrozenCallback callback, void *data) {
+  s_frozen_callback = callback;
+  s_frozen_callback_data = data;
+
+  launcher_task_add_callback(prv_compositor_freeze_cb, NULL);
 }
 
 static void prv_compositor_unfreeze_cb(void *ignored) {

src/fw/services/compositor/screenshot_pp.c

@@ -196,6 +196,10 @@ void screenshot_send_next_chunk(void* raw_state) {
   system_task_add_callback(screenshot_send_next_chunk, state);
 }
 
+static void prv_frozen_cb(void *data) {
+  system_task_add_callback(screenshot_send_next_chunk, data);
+}
+
 void screenshot_protocol_msg_callback(CommSession *session, const uint8_t* msg_data, unsigned int msg_len) {
   uint8_t sub_command = msg_data[0];
   if (sub_command != 0x00) {
@@ -215,8 +219,6 @@ void screenshot_protocol_msg_callback(CommSession *session, const uint8_t* msg_d
 
   prv_request_fast_connection(session);
 
-  compositor_freeze();
-
   s_screenshot_state = (ScreenshotState) {
     .session = session,
     .framebuffer =  (FrameBufferState) {
@@ -229,5 +231,5 @@ void screenshot_protocol_msg_callback(CommSession *session, const uint8_t* msg_d
     .sent_header = false,
   };
 
-  screenshot_send_next_chunk(&s_screenshot_state);
+  compositor_freeze(prv_frozen_cb, &s_screenshot_state);
 }

src/fw/services/light/console.c

@@ -80,6 +80,11 @@ void command_als_lux(void) {
 
 // Set by prv_als_flush_cb on KernelMain once the panel update is kicked.
 static volatile bool s_als_flush_done;
+static volatile bool s_als_frozen;
+
+static void prv_als_frozen_cb(void *unused) {
+  s_als_frozen = true;
+}
 
 // Runs on KernelMain (the compositor's task): push the staged system framebuffer
 // to the panel, the same way the PULSE framebuffer domain does.
@@ -134,8 +139,9 @@ void command_als_curve(void) {
   };
 
   animation_private_pause();
-  compositor_freeze();
-  while (compositor_display_update_in_progress()) {
+  s_als_frozen = false;
+  compositor_freeze(prv_als_frozen_cb, NULL);
+  while (!s_als_frozen) {
     psleep(2);
   }
 

tests/fw/services/compositor/test_compositor.c

@@ -196,7 +196,24 @@ static const CompositorTransition s_transition_b = {
   .update = prv_compositor_update_func_b
 };
 
+static void (*s_launcher_callback)(void *data);
+static void *s_launcher_callback_data;
 void launcher_task_add_callback(void (*callback)(void *data), void *data) {
+  s_launcher_callback = callback;
+  s_launcher_callback_data = data;
+}
+
+static void prv_run_launcher_callback(void) {
+  void (*callback)(void *data) = s_launcher_callback;
+  s_launcher_callback = NULL;
+  callback(s_launcher_callback_data);
+}
+
+static int s_count_frozen = 0;
+static void *s_frozen_data;
+static void prv_frozen_cb(void *data) {
+  ++s_count_frozen;
+  s_frozen_data = data;
 }
 
 
@@ -226,6 +243,11 @@ void test_compositor__initialize(void) {
 
   s_render_pending = false;
 
+  s_launcher_callback = NULL;
+  s_launcher_callback_data = NULL;
+  s_count_frozen = 0;
+  s_frozen_data = NULL;
+
   compositor_init();
 }
 
@@ -443,3 +465,49 @@ void test_compositor__cancel_modal_to_app_with_another_modal(void) {
   // App should be free to render again
   cl_assert_equal_i(s_render_pending, false);
 }
+
+void test_compositor__freeze_idle_display(void) {
+  int data;
+  compositor_freeze(prv_frozen_cb, &data);
+  // Nothing happens until the freeze runs on KernelMain
+  cl_assert_equal_i(s_count_frozen, 0);
+  compositor_app_render_ready();
+  cl_assert_equal_i(s_count_display_update, 1);
+
+  // No display update in flight: the callback fires as soon as the freeze takes effect
+  prv_run_launcher_callback();
+  cl_assert_equal_i(s_count_frozen, 1);
+  cl_assert_equal_p(s_frozen_data, &data);
+
+  // Frames are held back while frozen
+  compositor_app_render_ready();
+  cl_assert_equal_i(s_count_display_update, 1);
+
+  // ... and flushed once unfrozen
+  compositor_unfreeze();
+  prv_run_launcher_callback();
+  cl_assert_equal_i(s_count_display_update, 2);
+  cl_assert_equal_i(s_count_frozen, 1);
+}
+
+void test_compositor__freeze_waits_for_display_update(void) {
+  s_display_update_in_progress = true;
+  compositor_freeze(prv_frozen_cb, NULL);
+  prv_run_launcher_callback();
+  // The framebuffer is still being pushed to the display, so it isn't stable yet
+  cl_assert_equal_i(s_count_frozen, 0);
+
+  compositor_app_render_ready();
+  cl_assert_equal_i(s_count_display_update, 0);
+
+  // The update completes: the deferred frame stays held back and the callback fires
+  s_display_update_in_progress = false;
+  prv_handle_display_update_complete();
+  cl_assert_equal_i(s_count_display_update, 0);
+  cl_assert_equal_i(s_count_frozen, 1);
+
+  compositor_unfreeze();
+  prv_run_launcher_callback();
+  cl_assert_equal_i(s_count_display_update, 1);
+  cl_assert_equal_i(s_count_frozen, 1);
+}