ra8_epaper.c

Go to the documentation of this file.

 
#include "ra8_epaper.h"
 
#include <stddef.h>
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"
#include "ra8_port_regs.h"
#include "ra8_port_utils.h"
#include "ra8_spi_bus_ops.h"
#include "ra8_time.h"

static const char* s_tag = "EPAPER";
 
/* =============================================================================
 * Constants -- typed enums per the no-magic-number rule.
 * =============================================================================
 */

typedef enum : uint16_t {
  k_ra8_epaper_preamble_cmd = 0x6000U, 
  k_ra8_epaper_preamble_wr  = 0x0000U, 
  k_ra8_epaper_preamble_rd  = 0x1000U, 
} ra8_epaper_preamble_t;

typedef enum : uint16_t {
  k_ra8_epaper_cmd_sys_run      = 0x0001U, 
  k_ra8_epaper_cmd_sleep        = 0x0003U, 
  k_ra8_epaper_cmd_reg_rd       = 0x0010U, 
  k_ra8_epaper_cmd_reg_wr       = 0x0011U, 
  k_ra8_epaper_cmd_ld_img_area  = 0x0021U, 
  k_ra8_epaper_cmd_ld_img_end   = 0x0022U, 
  k_ra8_epaper_cmd_dpy_area     = 0x0034U, 
  k_ra8_epaper_cmd_vcom         = 0x0039U, 
  k_ra8_epaper_cmd_get_dev_info = 0x0302U, 
} ra8_epaper_cmd_t;

typedef enum : uint16_t {
  k_ra8_epaper_vcom_get = 0x0000U, 
  k_ra8_epaper_vcom_set = 0x0001U, 
} ra8_epaper_vcom_arg_t;

typedef enum : uint16_t {
  k_ra8_epaper_reg_lisar_lo = 0x0208U, 
  k_ra8_epaper_reg_lisar_hi = 0x020AU, 
  k_ra8_epaper_reg_lutafsr  = 0x1224U, 
} ra8_epaper_reg_t;

typedef enum : uint32_t {
  k_ra8_epaper_busy_poll_max  = 200000U, 
  k_ra8_epaper_lut_poll_max   = 200000U, 
  k_ra8_epaper_dev_info_words = 20U,     
  k_ra8_epaper_reset_pulse_ms = 10U,     
  k_ra8_epaper_status_unset   = 0xFFFFU, 
  k_ra8_epaper_byte_mask      = 0xFFU,   
  k_ra8_epaper_dummy_tx       = 0xFFU,   
  k_ra8_epaper_white_pad      = 0x00FFU, 
  k_ra8_epaper_byte_shift     = 8U,      
  k_ra8_epaper_pf_shift       = 4U,      
} ra8_epaper_limits_t;

typedef enum : uint16_t {
  k_ra8_epaper_wire_pf_2bpp = 0U, 
  k_ra8_epaper_wire_pf_3bpp = 1U, 
  k_ra8_epaper_wire_pf_4bpp = 2U, 
  k_ra8_epaper_wire_pf_8bpp = 3U, 
} ra8_epaper_wire_pf_t;

typedef enum : uint8_t {
  k_ra8_epaper_state_uninit = 0U, 
  k_ra8_epaper_state_ready  = 1U, 
} ra8_epaper_state_t;

typedef struct {
  ra8_epaper_cfg_t      cfg;           
  ra8_epaper_dev_info_t info;          
  ra8_epaper_state_t    state;         
  uint16_t              vcom_mv;       
  bool                  vcom_verified; 
} ra8_epaper_panel_t;

static ra8_epaper_panel_t s_panel;
 
/* =============================================================================
 * Low-level SPI helpers
 * =============================================================================
 */

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_send16(uint16_t word)
{
  const ra8_spi_bus_ops_t* bus = &s_panel.cfg.bus;
  uint8_t                  hi =
    (uint8_t)((word >> (uint16_t)k_ra8_epaper_byte_shift) & (uint16_t)k_ra8_epaper_byte_mask);
  uint8_t   lo  = (uint8_t)(word & (uint16_t)k_ra8_epaper_byte_mask);
  uint8_t   rx  = 0U;
  ra8_err_t err = bus->xfer8(bus->ctx, hi, &rx);
  if (err != k_ra8_ok) {
    return err;
  }
  return bus->xfer8(bus->ctx, lo, &rx);
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_recv16(uint16_t* out_word)
{
  const ra8_spi_bus_ops_t* bus = &s_panel.cfg.bus;
  uint8_t                  hi  = 0U;
  uint8_t                  lo  = 0U;
  ra8_err_t                err = bus->xfer8(bus->ctx, (uint8_t)k_ra8_epaper_dummy_tx, &hi);
  if (err != k_ra8_ok) {
    return err;
  }
  err = bus->xfer8(bus->ctx, (uint8_t)k_ra8_epaper_dummy_tx, &lo);
  if (err != k_ra8_ok) {
    return err;
  }
  *out_word = (uint16_t)(((uint16_t)hi << (uint16_t)k_ra8_epaper_byte_shift) | (uint16_t)lo);
  return k_ra8_ok;
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_wait_ready(void)
{
  const ra8_port_pin_t pin = (ra8_port_pin_t)s_panel.cfg.busy_pin;
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
  volatile const void* hrdy_key = (volatile const void*)&ra8_port(RA8_PIN_PORT(pin))->PCNTR2;
#endif
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_epaper_busy_poll_max; i++) {
    ra8_level_t level = k_ra8_level_low;
    bool        ready = false;
    if (ra8_gpio_read(pin, &level) == k_ra8_ok) {
      ready = (level == k_ra8_level_high);
    }
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    if (ra8_fake_mmio_wait_eval(hrdy_key, i, ready)) {
      return k_ra8_ok;
    }
#else
    if (ready) {
      return k_ra8_ok;
    }
#endif
  }
  ra8_log_error(s_tag, "HRDY poll timeout");
  return k_ra8_err_hw_timeout;
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_write_cmd(uint16_t cmd)
{
  ra8_err_t err = internal_ra8_epaper_wait_ready();
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_send16((uint16_t)k_ra8_epaper_preamble_cmd);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_wait_ready();
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_ra8_epaper_send16(cmd);
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_write_data16(uint16_t word)
{
  ra8_err_t err = internal_ra8_epaper_wait_ready();
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_send16((uint16_t)k_ra8_epaper_preamble_wr);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_wait_ready();
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_ra8_epaper_send16(word);
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_read_data16(uint16_t* out_word)
{
  ra8_err_t err = internal_ra8_epaper_wait_ready();
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_send16((uint16_t)k_ra8_epaper_preamble_rd);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_wait_ready();
  if (err != k_ra8_ok) {
    return err;
  }
  /* IT8951 inserts one dummy word after the read preamble (DS 3.4). */
  uint16_t dummy = 0U;
  err            = internal_ra8_epaper_recv16(&dummy);
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_ra8_epaper_recv16(out_word);
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_reg_write(uint16_t reg, uint16_t value)
{
  ra8_err_t err = internal_ra8_epaper_write_cmd((uint16_t)k_ra8_epaper_cmd_reg_wr);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_write_data16(reg);
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_ra8_epaper_write_data16(value);
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_reg_read(uint16_t reg, uint16_t* value)
{
  ra8_err_t err = internal_ra8_epaper_write_cmd((uint16_t)k_ra8_epaper_cmd_reg_rd);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_write_data16(reg);
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_ra8_epaper_read_data16(value);
}

RA8_INTERNAL
static void internal_ra8_epaper_pulse_reset(void)
{
  const ra8_port_pin_t pin = (ra8_port_pin_t)s_panel.cfg.reset_pin;
  (void)ra8_gpio_write(pin, k_ra8_level_high);
  ra8_delay_ms((uint32_t)k_ra8_epaper_reset_pulse_ms);
  (void)ra8_gpio_write(pin, k_ra8_level_low);
  ra8_delay_ms((uint32_t)k_ra8_epaper_reset_pulse_ms);
  (void)ra8_gpio_write(pin, k_ra8_level_high);
  ra8_delay_ms((uint32_t)k_ra8_epaper_reset_pulse_ms);
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_read_dev_info(ra8_epaper_dev_info_t* out)
{
  uint16_t  words[k_ra8_epaper_dev_info_words] = {};
  ra8_err_t err = internal_ra8_epaper_write_cmd((uint16_t)k_ra8_epaper_cmd_get_dev_info);
  if (err != k_ra8_ok) {
    return err;
  }
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_epaper_dev_info_words; i++) {
    err = internal_ra8_epaper_read_data16(&words[i]);
    if (err != k_ra8_ok) {
      return err;
    }
  }
  /* Buffer the whole block, then decode it in one pure pass -- the decode
   * lives in ra8_epaper_devinfo.c so it is testable without a bus. */
  return ra8_epaper_decode_dev_info(words, (size_t)k_ra8_epaper_dev_info_words, out);
}

RA8_INTERNAL
[[nodiscard]] static uint16_t internal_ra8_epaper_wire_pf(ra8_epaper_pixel_format_t pf)
{
  switch (pf) {
    case k_ra8_epaper_pf_2bpp:
      return (uint16_t)k_ra8_epaper_wire_pf_2bpp;
    case k_ra8_epaper_pf_4bpp:
      return (uint16_t)k_ra8_epaper_wire_pf_4bpp;
    case k_ra8_epaper_pf_1bpp:
    case k_ra8_epaper_pf_8bpp:
    default:
      return (uint16_t)k_ra8_epaper_wire_pf_8bpp;
  }
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_send_load_args(const ra8_epaper_area_t*  area,
                                                                  ra8_epaper_pixel_format_t pf,
                                                                  ra8_epaper_endian_t       endian)
{
  /* DS 4.2.7 LD_IMG_AREA argument layout:
   *   arg0 = (endian << 8) | (pf << 4) | rotate
   *   arg1..arg4 = x, y, width, height
   */
  const uint16_t arg0 =
    (uint16_t)(((uint16_t)endian << (uint16_t)k_ra8_epaper_byte_shift) |
               (internal_ra8_epaper_wire_pf(pf) << (uint16_t)k_ra8_epaper_pf_shift));
  ra8_err_t err = internal_ra8_epaper_write_data16(arg0);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_write_data16(area->x);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_write_data16(area->y);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_write_data16(area->width);
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_ra8_epaper_write_data16(area->height);
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_stream_pixels(const uint8_t* buf, size_t buf_len)
{
  for (size_t i = 0U; (i + 1U) < buf_len; i += 2U) {
    const uint16_t word =
      (uint16_t)(((uint16_t)buf[i] << (uint16_t)k_ra8_epaper_byte_shift) | (uint16_t)buf[i + 1U]);
    ra8_err_t err = internal_ra8_epaper_write_data16(word);
    if (err != k_ra8_ok) {
      return err;
    }
  }
  if ((buf_len & 1U) != 0U) {
    const uint16_t word =
      (uint16_t)(((uint16_t)buf[buf_len - 1U] << (uint16_t)k_ra8_epaper_byte_shift) |
                 (uint16_t)k_ra8_epaper_white_pad);
    return internal_ra8_epaper_write_data16(word);
  }
  return k_ra8_ok;
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_resolve_waveform(ra8_epaper_waveform_t waveform,
                                                                    uint16_t*             out_mode)
{
  const ra8_epaper_waveform_cfg_t* wf = &s_panel.cfg.waveform;
  switch (waveform) {
    case k_ra8_epaper_wf_init:
      *out_mode = (uint16_t)wf->init;
      return k_ra8_ok;
    case k_ra8_epaper_wf_du:
      *out_mode = (uint16_t)wf->du;
      return k_ra8_ok;
    case k_ra8_epaper_wf_gc16:
      *out_mode = (uint16_t)wf->gc16;
      return k_ra8_ok;
    case k_ra8_epaper_wf_a2:
      *out_mode = (uint16_t)wf->a2;
      return k_ra8_ok;
    default:
      return k_ra8_err_invalid_arg;
  }
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_send_display_args(const ra8_epaper_area_t* area,
                                                                     uint16_t wf_mode)
{
  ra8_err_t err = internal_ra8_epaper_write_data16(area->x);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_write_data16(area->y);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_write_data16(area->width);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_write_data16(area->height);
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_ra8_epaper_write_data16(wf_mode);
}
 
/* =============================================================================
 * Public API
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_epaper_init(const ra8_epaper_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "epaper_init: cfg null");
 
  if (s_panel.state != k_ra8_epaper_state_uninit) {
    ra8_log_error(s_tag, "epaper_init: already initialized");
    return k_ra8_err_invalid_state;
  }
  ra8_err_t err = ra8_epaper_validate_cfg(cfg);
  if (err != k_ra8_ok) {
    ra8_log_error(s_tag, "epaper_init: cfg field out of range");
    return err;
  }
 
  s_panel.cfg = *cfg;
  /* A fresh controller has been given no VCOM by us, so the INV-VCOM-1
   * permit starts revoked. Only a verified ``ra8_epaper_set_vcom`` grants
   * it, and until then every display command is refused. */
  s_panel.vcom_verified = false;
  s_panel.vcom_mv       = 0U;
 
  internal_ra8_epaper_pulse_reset();
  err = internal_ra8_epaper_wait_ready();
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_write_cmd((uint16_t)k_ra8_epaper_cmd_sys_run);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_read_dev_info(&s_panel.info);
  if (err != k_ra8_ok) {
    return err;
  }
  if (!ra8_epaper_geometry_agrees(&s_panel.info, cfg)) {
    /* Reported geometry disagrees with the descriptor. Logged, not fatal:
     * a controller that has not finished loading its waveform answers the
     * first GET_DEV_INFO with zeroes, and the app may legitimately drive a
     * sub-window of a larger panel. */
    ra8_log_warn(s_tag, "epaper_init: GET_DEV_INFO geometry differs from cfg");
  }
 
  s_panel.state = k_ra8_epaper_state_ready;
  ra8_log_info(s_tag, "epaper_init ok");
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_epaper_dev_info(ra8_epaper_dev_info_t* out_info)
{
  RA8_CHECK_NULL_PTR(out_info, s_tag, "dev_info: out null");
  if (s_panel.state != k_ra8_epaper_state_ready) {
    return k_ra8_err_invalid_state;
  }
  *out_info = s_panel.info;
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_epaper_get_vcom(uint16_t* out_mv)
{
  RA8_CHECK_NULL_PTR(out_mv, s_tag, "get_vcom: out null");
  if (s_panel.state != k_ra8_epaper_state_ready) {
    return k_ra8_err_invalid_state;
  }
  ra8_err_t err = internal_ra8_epaper_write_cmd((uint16_t)k_ra8_epaper_cmd_vcom);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_write_data16((uint16_t)k_ra8_epaper_vcom_get);
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_ra8_epaper_read_data16(out_mv);
}

[[nodiscard]] ra8_err_t ra8_epaper_set_vcom(uint16_t mv)
{
  if (s_panel.state != k_ra8_epaper_state_ready) {
    return k_ra8_err_invalid_state;
  }
  if (mv == 0U) {
    ra8_log_error(s_tag, "set_vcom: refusing a zero VCOM");
    return k_ra8_err_invalid_arg;
  }
 
  /* Revoke first. Every early return below then leaves the panel
   * un-drivable rather than trusting a half-completed write, and a second
   * set_vcom that fails cannot leave the previous call's permit standing. */
  s_panel.vcom_verified = false;
  s_panel.vcom_mv       = 0U;
 
  ra8_err_t err = internal_ra8_epaper_write_cmd((uint16_t)k_ra8_epaper_cmd_vcom);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_write_data16((uint16_t)k_ra8_epaper_vcom_set);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_write_data16(mv);
  if (err != k_ra8_ok) {
    return err;
  }
 
  /* Read it straight back. A silently dead COPI line, a controller that
   * NAKs the command, or a bus stuck returning zeroes all accept the write
   * and change nothing -- a failure mode indistinguishable from success
   * without this compare, and one that would leave the film biased at the
   * controller's own unknown value. */
  uint16_t readback = 0U;
  err               = ra8_epaper_get_vcom(&readback);
  if (err != k_ra8_ok) {
    return err;
  }
  if (readback != mv) {
    ra8_log_error(s_tag, "set_vcom: readback mismatch -- panel stays dark");
    return k_ra8_err_validation_failed;
  }
 
  s_panel.vcom_mv       = mv;
  s_panel.vcom_verified = true;
  return k_ra8_ok;
}

[[nodiscard]] bool ra8_epaper_vcom_verified(void)
{
  /* Deliberately not `(state == ready) && vcom_verified`. The latch is set
   * only by a set_vcom that ran in the ready state and is cleared by both
   * init and sleep, so `vcom_verified` implies `state == ready` -- see the
   * ra8_epaper_panel_t invariant. Testing the state as well would add a
   * condition no test could ever vary independently, which is an
   * untestable branch rather than defence in depth. */
  return s_panel.vcom_verified;
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_validate_load(const ra8_epaper_area_t*  area,
                                                                 size_t                    buf_len,
                                                                 ra8_epaper_pixel_format_t pf)
{
  if (s_panel.state != k_ra8_epaper_state_ready) {
    return k_ra8_err_invalid_state;
  }
  size_t          expect = 0U;
  const ra8_err_t serr   = ra8_epaper_image_bytes(area, pf, &expect);
  if ((serr != k_ra8_ok) || (buf_len != expect)) {
    return k_ra8_err_invalid_size;
  }
  if (!ra8_epaper_area_is_aligned(area, pf)) {
    ra8_log_error(s_tag, "load_image: 1bpp area violates 32px X/width alignment");
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_epaper_load_image(const ra8_epaper_area_t*  area,
                                              const uint8_t*            buf,
                                              size_t                    buf_len,
                                              ra8_epaper_pixel_format_t pf,
                                              ra8_epaper_endian_t       endian)
{
  RA8_CHECK_NULL_PTR(area, s_tag, "load_image: area null");
  RA8_CHECK_NULL_PTR(buf, s_tag, "load_image: buf null");
 
  const ra8_err_t verr = internal_ra8_epaper_validate_load(area, buf_len, pf);
  if (verr != k_ra8_ok) {
    return verr;
  }
 
  /* DS 4.4 -- LISAR holds the 32-bit target frame address; on a
   * single-image driver we keep image base at 0 (the controller's
   * default frame buffer after SYS_RUN). */
  ra8_err_t err = internal_ra8_epaper_reg_write((uint16_t)k_ra8_epaper_reg_lisar_lo, 0U);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_reg_write((uint16_t)k_ra8_epaper_reg_lisar_hi, 0U);
  if (err != k_ra8_ok) {
    return err;
  }
 
  err = internal_ra8_epaper_write_cmd((uint16_t)k_ra8_epaper_cmd_ld_img_area);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_send_load_args(area, pf, endian);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_stream_pixels(buf, buf_len);
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_ra8_epaper_write_cmd((uint16_t)k_ra8_epaper_cmd_ld_img_end);
}

RA8_INTERNAL
[[nodiscard]] static ra8_err_t internal_ra8_epaper_wait_lut_idle(void)
{
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
  /* Not a register access: the address is only used as a fault-table key. */
  volatile const void* lut_probe = (volatile const void*)s_panel.cfg.bus.ctx;
#endif
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_epaper_lut_poll_max; i++) {
    uint16_t        status = (uint16_t)k_ra8_epaper_status_unset;
    const ra8_err_t err = internal_ra8_epaper_reg_read((uint16_t)k_ra8_epaper_reg_lutafsr, &status);
    if (err != k_ra8_ok) {
      return err;
    }
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    if (ra8_fake_mmio_wait_eval(lut_probe, i, (status == 0U))) {
      return k_ra8_ok;
    }
#else
    if (status == 0U) {
      return k_ra8_ok;
    }
#endif
  }
  return k_ra8_err_hw_timeout;
}
 
[[nodiscard]] ra8_err_t ra8_epaper_display_area(const ra8_epaper_area_t* area,
                                                ra8_epaper_waveform_t    waveform)
{
  RA8_CHECK_NULL_PTR(area, s_tag, "display_area: area null");
 
  if (s_panel.state != k_ra8_epaper_state_ready) {
    return k_ra8_err_invalid_state;
  }
  /* INV-VCOM-1. DPY_AREA is the command that actually biases the film, so
   * this is the one place the invariant has to hold. Loading pixels into
   * frame RAM applies no bias and is deliberately left ungated -- an app
   * may stage a full frame before calibration completes. */
  if (!s_panel.vcom_verified) {
    ra8_log_error(s_tag, "display_area: no verified VCOM -- refusing (INV-VCOM-1)");
    return k_ra8_err_validation_failed;
  }
  uint16_t  wf_mode = 0U;
  ra8_err_t err     = internal_ra8_epaper_resolve_waveform(waveform, &wf_mode);
  if (err != k_ra8_ok) {
    ra8_log_error(s_tag, "display_area: unknown waveform selector");
    return err;
  }
 
  err = internal_ra8_epaper_write_cmd((uint16_t)k_ra8_epaper_cmd_dpy_area);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_ra8_epaper_send_display_args(area, wf_mode);
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_ra8_epaper_wait_lut_idle();
}
 
[[nodiscard]] ra8_err_t ra8_epaper_sleep(void)
{
  if (s_panel.state != k_ra8_epaper_state_ready) {
    return k_ra8_err_invalid_state;
  }
  ra8_err_t err = internal_ra8_epaper_write_cmd((uint16_t)k_ra8_epaper_cmd_sleep);
  /* Whether the SLEEP command made it out or not, the controller is
   * no longer in a defined state from the driver's perspective -- and a
   * controller that may have dropped its VCOM must not inherit the permit
   * across the next init. */
  s_panel.state         = k_ra8_epaper_state_uninit;
  s_panel.vcom_verified = false;
  s_panel.vcom_mv       = 0U;
  return err;
}