ra8_glcdc.c

Go to the documentation of this file.

 
#include "ra8_glcdc.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_glcdc_regs.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
 
static const char* s_tag = "GLCDC";
 
/* =============================================================================
 * Local constants
 * =============================================================================
 */

typedef enum : uint32_t {
  k_glcdc_clut_size = 0x10000UL, 
} glcdc_clut_t;
 
typedef enum : uint8_t {
  k_ra8_glcdc_layer_count   = 2U,  
  k_ra8_glcdc_layer1        = 0U,  
  k_ra8_glcdc_dispsel_below = 1U,  
  k_ra8_glcdc_dispsel_above = 2U,  
  k_ra8_glcdc_arcdef_shift  = 16U, 
  k_ra8_glcdc_clutsel_shift = 16U, 
  k_ra8_glcdc_pdtha_shift   = 8U,  
  k_ra8_glcdc_word_shift    = 16U, 
  k_ra8_glcdc_g_shift       = 16U, 
  k_ra8_glcdc_b_shift       = 8U,  
} ra8_glcdc_priv_const_t;
 
typedef enum : uint16_t {
  k_ra8_glcdc_clut_entries = 256U, 
} ra8_glcdc_clut_const_t;
 
typedef enum : uint32_t {
  k_ra8_glcdc_clutsel_mask = 0x10000UL, 
  k_ra8_glcdc_arcon_mask   = 0x1000UL,  
} ra8_glcdc_priv_mask_t;
 
/* =============================================================================
 * Initialisation
 * =============================================================================
 */
 
/* =============================================================================
 * RA8D2-specific power + clock bring-up that FSP's R_GLCDC_Open expects to
 * have been done by the BSP before it touches any GLCDC register.  Without
 * these two steps the entire GLCDC register window at 0x40342000 silently
 * drops reads and writes (the chip's Graphics power domain is off and
 * LCDCLK is parked on the default MOCO).
 *
 *   PDCTRGD.PDDE = 0   power on the Graphics power domain
 *   LCDCKCR = PLL2P    LCDCLK = 240 MHz on PLL2P
 *
 * Both writes are PRCR-protected (LPM and CGC groups respectively).
 * =============================================================================
 */

/* HUM Ch 11.2.1 "PRCR : Protect Register" p 440 -- PRC0 (bit 0)
 * unlocks CGC; PRC1 (bit 1) unlocks LPM. Key = 0xA5xx. */
enum : uintptr_t {
  k_addr_prcr       = 0x4001E3FAUL, 
  k_addr_pdctrgd    = 0x4001E110UL, 
  k_addr_lcdckdivcr = 0x4001E05EUL, 
  k_addr_lcdckcr    = 0x4001E05FUL, 
  k_addr_hococr     = 0x4001E036UL, 
};
enum : uint16_t {
  k_prcr_unlock_lpm = 0xA502U, 
  k_prcr_unlock_cgc = 0xA501U, 
  k_prcr_relock     = 0xA500U, 
};
enum : uint8_t {
  k_pdctrgd_on      = 0x00U, 
  k_pdctrgd_pdcsf   = 0x40U, 
  k_pdctrgd_pdpgsf  = 0x80U, 
  k_pdctrgd_status  = 0xC0U, 
  k_lcdck_sreq      = 0x40U, 
  k_lcdck_srdy_mask = 0x80U, 
  k_lcdck_sel_pll1r = 0x08U, 
  k_lcdckdivcr_div4 = 0x02U, 
  k_hococr_run      = 0x00U, 
};

RA8_INTERNAL
static void internal_hoco_enable(void)
{
  volatile uint16_t* const prcr   = (volatile uint16_t*)k_addr_prcr;
  volatile uint8_t* const  hococr = (volatile uint8_t*)k_addr_hococr;
  *prcr                           = (uint16_t)k_prcr_unlock_cgc;
  *hococr                         = (uint8_t)k_hococr_run;
  *prcr                           = (uint16_t)k_prcr_relock;
}

RA8_INTERNAL
static void internal_graphics_domain_power_on(void)
{
  volatile uint16_t* const prcr    = (volatile uint16_t*)k_addr_prcr;
  volatile uint8_t* const  pdctrgd = (volatile uint8_t*)k_addr_pdctrgd;
  *prcr                            = (uint16_t)k_prcr_unlock_lpm;
 
  /* Wait for "fully gated" state before issuing the power-on request. */
  for (uint32_t i = 0U; i < k_glcdc_clut_size; i++) {
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    /* Host MMIO fault seam: tests drive the retry / exhaustion legs. */
    const bool pdpgsf_now = (*pdctrgd & (uint8_t)k_pdctrgd_status) == (uint8_t)k_pdctrgd_pdpgsf;
    if (ra8_fake_mmio_wait_eval(pdctrgd, i, pdpgsf_now)) {
      break;
    }
#else
    if ((*pdctrgd & (uint8_t)k_pdctrgd_status) == (uint8_t)k_pdctrgd_pdpgsf) {
      break;
    }
#endif
  }
  *pdctrgd = (uint8_t)k_pdctrgd_on;
  /* Wait for "fully on" state -- both PDCSF and PDPGSF must clear. */
  for (uint32_t i = 0U; i < k_glcdc_clut_size; i++) {
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    if (ra8_fake_mmio_wait_eval(pdctrgd, i, ((*pdctrgd & (uint8_t)k_pdctrgd_status) == 0U))) {
      break;
    }
#else
    if ((*pdctrgd & (uint8_t)k_pdctrgd_status) == 0U) {
      break;
    }
#endif
  }
  *prcr = (uint16_t)k_prcr_relock;
}

RA8_INTERNAL
static void internal_lcdclk_switch_pll1r(void)
{
  volatile uint16_t* const prcr       = (volatile uint16_t*)k_addr_prcr;
  volatile uint8_t* const  lcdckdivcr = (volatile uint8_t*)k_addr_lcdckdivcr;
  volatile uint8_t* const  lcdckcr    = (volatile uint8_t*)k_addr_lcdckcr;
 
  *prcr    = (uint16_t)k_prcr_unlock_cgc;
  *lcdckcr = (uint8_t)k_lcdck_sreq;
  for (uint32_t i = 0U; i < k_glcdc_clut_size; i++) {
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    /* Host MMIO fault seam: tests drive the retry / exhaustion legs. */
    if (ra8_fake_mmio_wait_eval(lcdckcr, i, ((*lcdckcr & (uint8_t)k_lcdck_srdy_mask) != 0U))) {
      break;
    }
#else
    if ((*lcdckcr & (uint8_t)k_lcdck_srdy_mask) != 0U) {
      break;
    }
#endif
  }
  *lcdckdivcr = (uint8_t)k_lcdckdivcr_div4;
  *lcdckcr    = (uint8_t)(k_lcdck_sreq | k_lcdck_sel_pll1r);
  *lcdckcr    = (uint8_t)k_lcdck_sel_pll1r;
  for (uint32_t i = 0U; i < k_glcdc_clut_size; i++) {
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    if (ra8_fake_mmio_wait_eval(lcdckcr, i, ((*lcdckcr & (uint8_t)k_lcdck_srdy_mask) == 0U))) {
      break;
    }
#else
    if ((*lcdckcr & (uint8_t)k_lcdck_srdy_mask) == 0U) {
      break;
    }
#endif
  }
  *prcr = (uint16_t)k_prcr_relock;
}

RA8_INTERNAL
static void internal_graphics_power_on(void)
{
  internal_hoco_enable();
  internal_graphics_domain_power_on();
  internal_lcdclk_switch_pll1r();
}
 
/* =============================================================================
 * Bit positions / shifts that FSP's r_glcdc.c uses verbatim.  Pulled from
 * the FSP private header constants ("GLCDC_PRV_*_SHIFT" / "_MASK") -- not
 * copied as code, just referenced for the register field layout.
 *
 *   OUT_SET.FORMAT[13:12]    output pixel format
 *   OUT_PDTHA.FORM[17:16]    dither output format (must match OUT_SET)
 *   FLM6.FORMAT[30:28]       framebuffer pixel format
 *   FLM3.LNOFF[31:16]        line stride in bytes
 *   FLM5.LNNUM[26:16]        lines per frame minus 1
 *   FLM5.DATANUM[15:0]       64-byte AXI bursts per line minus 1
 *   AB3.GRCHS[26:16]/W[10:0] graphics layer H position + width
 *   AB2.GRCVS[26:16]/W[10:0] graphics layer V position + height
 *   AB7.ARCDEF[23:16]        constant alpha for alpha-rect
 *   BG_HSIZE.HP[26:16]       BG active-pixel start position
 *   BG_VSIZE.VP[26:16]       BG active-line start position
 *   BG_SYNC HP / VP min = 1  (HUM 63 p 3760)
 * =============================================================================
 */
typedef enum : uint32_t {
  k_glcdc_shift_high       = 16U, 
  k_glcdc_shift_flm6_fmt   = 28U, 
  k_glcdc_shift_outset_fmt = 12U, 
  k_glcdc_shift_pdtha_fmt  = 16U, 
  k_glcdc_shift_arcdef     = 16U, 
  k_glcdc_axi_burst_bytes  = 64U, 
  k_glcdc_bpp_rgb565       = 2U,  
  k_glcdc_sync_pos_min     = 1U,  
} ra8_glcdc_layout_priv_t;
 
/* SEL[2:0] values for TCON_STXx2.SEL (HUM 63 p 3805) */
typedef enum : uint32_t {
  k_glcdc_sel_stva = 0U, 
  k_glcdc_sel_stvb = 1U, 
  k_glcdc_sel_stha = 2U, 
  k_glcdc_sel_de   = 7U, 
} ra8_glcdc_tcon_sel_t;
 
/* GR.AB1.DISPSEL[1:0] (HUM 63 p 3744 + FSP enum):
 *   1 = TRANSPARENT  -- layer hidden, lower layer (BG) shows through
 *   2 = NON_TRANSPARENT -- this layer's pixels are output */
typedef enum : uint32_t {
  k_glcdc_dispsel_transparent     = 1U, 
  k_glcdc_dispsel_non_transparent = 2U, 
} ra8_glcdc_dispsel_priv_t;
 
/* AB7.ARCDEF[23:16] alpha constants. */
typedef enum : uint32_t {
  k_glcdc_alpha_opaque = 0xFFUL, 
} ra8_glcdc_alpha_priv_t;
 
/* Panel timing is supplied by the caller via ra8_glcdc_config_t.timing -- it is
 * accessory data, not a peripheral property, so the panel's values (e.g. the
 * EK-RA8D2 ER-TFT070-6) live in the board BSP (libs/ra8_board_ek_ra8d2), not in
 * this driver. */
 
/* OUT_SET.FORMAT[1:0] codes for output bus. */
typedef enum : uint32_t {
  k_glcdc_out_set_rgb888 = 0U, 
  k_glcdc_out_set_rgb666 = 1U, 
  k_glcdc_out_set_rgb565 = 2U, 
} ra8_glcdc_out_set_fmt_t;
 
/* OUT_PDTHA.FORM[1:0] codes -- must match OUT_SET.FORMAT for non-serial. */
typedef enum : uint32_t {
  k_glcdc_pdtha_rgb888 = 0U, 
  k_glcdc_pdtha_rgb666 = 1U, 
  k_glcdc_pdtha_rgb565 = 2U, 
} ra8_glcdc_pdtha_fmt_t;

typedef struct {
  uint32_t h_active; 
  uint32_t h_back;   
  uint32_t h_sync;   
  uint32_t h_total;  
  uint32_t v_active; 
  uint32_t v_back;   
  uint32_t v_sync;   
  uint32_t v_total;  
} ra8_glcdc_panel_timing_t;

RA8_INTERNAL
static void internal_program_tcon(const ra8_glcdc_panel_timing_t* t)
{
  *ra8_glcdc_reg32(k_ra8_glcdc_off_out_clkphase) = 0U; /* all rising edge */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_tcon_tim)     = 0U;
 
  /* STVA -> LCD_TCON0 (VSYNC, active-low: INV=1). */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_tcon_stva1) = t->v_sync;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_tcon_stva2) = (uint32_t)k_glcdc_sel_stva | (1UL << 4);
 
  /* STHA pulse width, DE -> LCD_TCON2 (active-high: INV=0). */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_tcon_stha1) = t->h_sync;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_tcon_stha2) = (uint32_t)k_glcdc_sel_de;
 
  /* STVB -> LCD_TCON1 (HSYNC routed via STVB2.SEL = STHA, active-low). */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_tcon_stvb1) =
    ((uint32_t)(t->v_sync + t->v_back) << k_glcdc_shift_high) | t->v_active;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_tcon_stvb2) = (uint32_t)k_glcdc_sel_stha | (1UL << 4);
 
  /* STHB encodes horizontal DE strobe; TCON3 unused on this board. */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_tcon_sthb1) =
    ((uint32_t)(t->h_sync + t->h_back) << k_glcdc_shift_high) | t->h_active;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_tcon_sthb2) = 0U;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_tcon_de)    = 0U;
}

RA8_INTERNAL
static void internal_program_bg(const ra8_glcdc_panel_timing_t* t)
{
  const uint32_t bg_h_pos                  = t->h_back + k_glcdc_sync_pos_min; /* FSP: back+1 */
  const uint32_t bg_v_pos                  = t->v_back + k_glcdc_sync_pos_min;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_bg_per) = (t->v_total << k_glcdc_shift_high) | t->h_total;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_bg_sync) =
    ((uint32_t)k_glcdc_sync_pos_min << k_glcdc_shift_high) | (uint32_t)k_glcdc_sync_pos_min;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_bg_hsize) = (bg_h_pos << k_glcdc_shift_high) | t->h_active;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_bg_vsize) = (bg_v_pos << k_glcdc_shift_high) | t->v_active;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_bg_bgc)   = 0U;
}

RA8_INTERNAL
static void internal_program_gr1(const ra8_glcdc_panel_timing_t* t,
                                 uintptr_t                       fb_addr,
                                 uint16_t                        fb_format,
                                 uint16_t                        fb_w,
                                 uint16_t                        fb_h)
{
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_fmt)   = ((uint32_t)fb_format << k_glcdc_shift_flm6_fmt);
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_saddr) = (uint32_t)fb_addr;
 
  /* FLM3.LNOFF (line stride) + FLM5 (active line / AXI-burst count)
   * track the FRAMEBUFFER dimensions, not the panel.  This lets a
   * small SRAM framebuffer occupy only a portion of the panel
   * (rest is filled by the BG plane via BG_BGC). */
  const uint32_t line_bytes                  = (uint32_t)fb_w * (uint32_t)k_glcdc_bpp_rgb565;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_flm3) = (line_bytes << k_glcdc_shift_high);
 
  const uint32_t datanum = (line_bytes / (uint32_t)k_glcdc_axi_burst_bytes) - 1U;
  const uint32_t lnnum   = (uint32_t)fb_h - 1U;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_line) = (lnnum << k_glcdc_shift_high) | datanum;
 
  /* Layer position on the panel: start at the back-porch corner
   * (top-left of the active area) so a small framebuffer renders
   * at the panel's origin and the rest stays BG-plane. */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_size) = (t->h_back << k_glcdc_shift_high) | (uint32_t)fb_w;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_ab2)  = (t->v_back << k_glcdc_shift_high) | (uint32_t)fb_h;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_ab4)  = (t->v_back << k_glcdc_shift_high) | (uint32_t)fb_h;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_ab5)  = (t->h_back << k_glcdc_shift_high) | (uint32_t)fb_w;
 
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_ab1)   = (uint32_t)k_glcdc_dispsel_transparent;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_flmrd) = 0U;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_ab7)   = 0UL;
}

RA8_INTERNAL
static void internal_program_gr2(const ra8_glcdc_panel_timing_t* t)
{
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr2_size)  = (t->h_back << k_glcdc_shift_high) | t->h_active;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr2_ab2)   = (t->v_back << k_glcdc_shift_high) | t->v_active;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr2_ab4)   = (t->v_back << k_glcdc_shift_high) | t->v_active;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr2_ab5)   = (t->h_back << k_glcdc_shift_high) | t->h_active;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr2_ab7)   = 0UL;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr2_ab1)   = (uint32_t)k_glcdc_dispsel_transparent;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr2_flmrd) = 0U;
}

RA8_INTERNAL
static void internal_program_out(void)
{
  enum : uint32_t {
    k_bright_mid   = 512UL, 
    k_contrast_mid = 128UL, 
  };
  *ra8_glcdc_reg32(k_ra8_glcdc_off_out_set) =
    ((uint32_t)k_glcdc_out_set_rgb888 << k_glcdc_shift_outset_fmt);
  *ra8_glcdc_reg32(k_ra8_glcdc_off_panel_dtha) =
    ((uint32_t)k_glcdc_pdtha_rgb888 << k_glcdc_shift_pdtha_fmt);
  *ra8_glcdc_reg32(k_ra8_glcdc_off_out_bright1) = k_bright_mid;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_out_bright2) = (k_bright_mid << 16) | k_bright_mid;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_out_contrast) =
    (k_contrast_mid << 16) | (k_contrast_mid << 8) | k_contrast_mid;
}

RA8_INTERNAL
static void internal_panel_program(uintptr_t                 fb_addr,
                                   uint16_t                  fb_format,
                                   uint16_t                  fb_w,
                                   uint16_t                  fb_h,
                                   const ra8_glcdc_timing_t* tm)
{
  const ra8_glcdc_panel_timing_t t = {
    .h_active = (uint32_t)tm->h_active,
    .h_back   = (uint32_t)tm->h_back,
    .h_sync   = (uint32_t)tm->h_sync,
    .h_total =
      (uint32_t)tm->h_active + (uint32_t)tm->h_front + (uint32_t)tm->h_back + (uint32_t)tm->h_sync,
    .v_active = (uint32_t)tm->v_active,
    .v_back   = (uint32_t)tm->v_back,
    .v_sync   = (uint32_t)tm->v_sync,
    .v_total =
      (uint32_t)tm->v_active + (uint32_t)tm->v_front + (uint32_t)tm->v_back + (uint32_t)tm->v_sync,
  };
  internal_program_tcon(&t);
  internal_program_bg(&t);
  internal_program_gr1(&t, fb_addr, fb_format, fb_w, fb_h);
  internal_program_gr2(&t);
  internal_program_out();
}
 
/* HUM Ch 63 "Graphics LCD Controller (GLCDC)" p 3744 */
ra8_err_t ra8_glcdc_init(const ra8_glcdc_config_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg must not be nullptr");
 
  /* HUM Ch 11.2.14 "PDCTRGD" p 452 + HUM Ch 9.2.58 "LCDCKCR" p 373.
   * Power on the Graphics domain and route LCDCLK to PLL2P.  Without
   * this the GLCDC peripheral bus is unreachable. */
  internal_graphics_power_on();
 
  /* HUM Ch 11.2.8 "MSTPCRC : Module Stop Control Register C", p 446 */
  const ra8_err_t mst_err = ra8_mstp_enable(k_ra8_mstp_glcdc);
  /* GCOVR_EXCL_BR_START -- MSTP HW readback: ra8_mstp_enable only fails when
   * the MSTPCR readback disagrees, which the host register file cannot stage. */
  RA8_RETURN_ON_ERROR(mst_err, s_tag, "glcdc_init: mstp enable");
  /* GCOVR_EXCL_BR_STOP */
 
  /* HUM Ch 63 "BG_EN.SWRST" p 3759 + FSP r_glcdc_open step 2.  Single
   * write of SWRST=1.  FSP uses a bit-field write (read-modify-write
   * leaving other bits at their reset values, which are all 0) -- a
   * plain `*reg = SWRST_MASK` is equivalent on a register that was
   * just out of reset. */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_bg_en) = (uint32_t)(1UL << 16);
 
  /* HUM Ch 63 "SYSCNT_PANEL_CLK" p 3813.  CLKSEL=LCDCLK, CLKEN=1,
   * DCDR=/5 -> 240 MHz / 5 = 48 MHz pixel clock. */
  enum : uint32_t {
    k_panel_clk_clksel_lcdclk = 1U << 8, 
    k_panel_clk_clken         = 1U << 6, 
    k_panel_clk_dcdr_div2     = 0x02U,   
  };
  /* LCDCLK = 100 MHz (PLL1R / 4), DCDR /2 -> pixel clock = 50 MHz.
   * Matches the LVGL EK-RA8D2 reference for the ER-TFT070-6 panel. */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_panel_clk) = (uint32_t)k_panel_clk_clksel_lcdclk |
                                                (uint32_t)k_panel_clk_clken |
                                                (uint32_t)k_panel_clk_dcdr_div2;
 
  /* Programme every other panel-side register in the FSP-documented order. */
  internal_panel_program(cfg->framebuffer_addr,
                         (uint16_t)cfg->format,
                         cfg->width_px,
                         cfg->height_px,
                         &cfg->timing);
 
  ra8_log_info_val(s_tag, "glcdc_init fb", cfg->framebuffer_addr);
  return k_ra8_ok;
}
 
ra8_err_t ra8_glcdc_start(bool enable)
{
  enum : uint32_t {
    k_bit_en    = 1U << 0,  
    k_bit_ven   = 1U << 8,  
    k_bit_swrst = 1U << 16, 
  };
 
  if (!enable) {
    /* Drop everything to disabled but keep SWRST high so register
     * reads keep working (writing SWRST=0 re-enters reset). */
    *ra8_glcdc_reg32(k_ra8_glcdc_off_bg_en)   = (uint32_t)k_bit_swrst;
    *ra8_glcdc_reg32(k_ra8_glcdc_off_sys_cfg) = 0U;
    return k_ra8_ok;
  }
 
  /* Match FSP's R_GLCDC_Start exactly: bit-field-style sequential writes
   * so SWRST stays high while we add VEN then EN.  Using read-modify-
   * write rather than full-word writes avoids momentarily clearing
   * SWRST or putting the controller in an undefined transition. */
  uint32_t bg_en = *ra8_glcdc_reg32(k_ra8_glcdc_off_bg_en);
 
  /* Step 1: VEN = 1 -- enable register value reflection on next VS. */
  bg_en |= (uint32_t)k_bit_ven;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_bg_en) = bg_en;
 
  /* Step 2: EN = 1 -- background plane operation enable. */
  bg_en |= (uint32_t)k_bit_en;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_bg_en) = bg_en;
 
  /* Step 3: SYSCNT.DTCTEN.VPOSDTC = 1 -- line-detect IRQ source. */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_sys_cfg) = 1U;
 
  /* Step 4: OUT_VLATCH.VEN = 1 -- commit the OUT_SET / OUT_PDTHA /
   * brightness / contrast shadow registers to the output stage's
   * working registers.  Without this the output-bus format we wrote
   * in init never reaches the pixel pipeline. */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_out_vlatch) = 1U;
 
  /* Step 5: GR1.VEN + GR2.VEN -- commit graphics-layer shadow regs.
   *
   * Both layers MUST be VEN-asserted, even if only one carries a
   * framebuffer.  See bring-up finding in internal_panel_program:
   * without GR2's shadow registers committed, the output pipeline's
   * lower-layer slot stays in reset and the panel sees solid black.
   * FSP r_glcdc_open writes PVEN on every layer it configured. */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_en) = 1U;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr2_en) = 1U;
 
  return k_ra8_ok;
}
 
/* =============================================================================
 * Output stage: dithering / brightness / contrast
 * =============================================================================
 */
 
ra8_err_t ra8_glcdc_set_dithering(ra8_glcdc_dither_mode_t mode)
{
  uint32_t sel;
  switch (mode) {
    case k_ra8_dither_off: {
      sel = 0U;
      break;
    }
    case k_ra8_dither_truncate: {
      sel = 2U;
      break;
    }
    case k_ra8_dither_2x2: {
      sel = 3U;
      break;
    }
    default: {
      return k_ra8_err_invalid_arg;
    }
  }
  /* HUM Ch 63 "OUT_PDTHA.SEL" p 3744 */ /* panel dither selector. */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_panel_dtha) = (sel << k_ra8_glcdc_pdtha_shift);
  return k_ra8_ok;
}
 
ra8_err_t ra8_glcdc_set_brightness(uint8_t r, uint8_t g, uint8_t b)
{
  /* HUM Ch 63 "OUT_BRIGHT1.BRTG" p 3744 */ /* green offset. */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_out_bright1) = (uint32_t)g;
 
  /* HUM Ch 63 "OUT_BRIGHT2.BRTB/BRTR" p 3744 */ /* blue + red offsets. */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_out_bright2) =
    ((uint32_t)b << k_ra8_glcdc_word_shift) | (uint32_t)r;
  return k_ra8_ok;
}
 
ra8_err_t ra8_glcdc_set_contrast(uint8_t r, uint8_t g, uint8_t b)
{
  /* HUM Ch 63 "OUT_CONTRAST.CONTG/CONTB/CONTR" p 3744 */
  *ra8_glcdc_reg32(k_ra8_glcdc_off_out_contrast) =
    ((uint32_t)g << k_ra8_glcdc_g_shift) | ((uint32_t)b << k_ra8_glcdc_b_shift) | (uint32_t)r;
  return k_ra8_ok;
}
 
/* =============================================================================
 * lifecycle + IRQ + power transition
 * =============================================================================
 */
 
static ra8_glcdc_event_fn_t s_glcdc_fn;
static void*                s_glcdc_ctx;
 
ra8_err_t ra8_glcdc_deinit(void)
{
  *ra8_glcdc_reg32(k_ra8_glcdc_off_sys_cfg) = 0U;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_bg_en)   = 0U;
  *ra8_glcdc_reg32(k_ra8_glcdc_off_gr1_en)  = 0U;
  s_glcdc_fn                                = nullptr;
  s_glcdc_ctx                               = nullptr;
  return ra8_mstp_disable(k_ra8_mstp_glcdc);
}
 
ra8_err_t ra8_glcdc_get_status(uint32_t* out_mask)
{
  RA8_CHECK_NULL_PTR(out_mask, s_tag, "out_mask must not be nullptr");
  *out_mask = *ra8_glcdc_reg32(k_ra8_glcdc_off_sys_stat);
  return k_ra8_ok;
}
 
ra8_err_t ra8_glcdc_clear_status(uint32_t mask)
{
  volatile uint32_t* reg = ra8_glcdc_reg32(k_ra8_glcdc_off_sys_stat);
  *reg                   = *reg & ~mask;
  return k_ra8_ok;
}
 
ra8_err_t ra8_glcdc_attach_handler(ra8_glcdc_event_fn_t fn, void* ctx)
{
  s_glcdc_fn  = fn;
  s_glcdc_ctx = ctx;
  return k_ra8_ok;
}
 
RA8_ISR_SAFE
void ra8_glcdc_dispatch(void)
{
  volatile uint32_t*         reg  = ra8_glcdc_reg32(k_ra8_glcdc_off_sys_stat);
  const uint32_t             mask = *reg;
  const ra8_glcdc_event_fn_t fn   = s_glcdc_fn;
  void* const                ctx  = s_glcdc_ctx;
  *reg                            = 0U;
  if (fn != nullptr) {
    fn(ctx, mask);
  }
}
 
ra8_err_t ra8_glcdc_enter_stop(void)
{
  *ra8_glcdc_reg32(k_ra8_glcdc_off_sys_cfg) = 0U;
  return ra8_mstp_disable(k_ra8_mstp_glcdc);
}
 
ra8_err_t ra8_glcdc_exit_stop(void)
{
  return ra8_mstp_enable(k_ra8_mstp_glcdc);
}