Graphics LCD Controller driver implementation. More...

#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"

Include dependency graph for ra8_glcdc.c:

Data Structures
struct	ra8_glcdc_panel_timing_t
	Panel timing parameters shared by the per-stage helpers. More...

Enumerations
enum	glcdc_clut_t : uint32_t { k_glcdc_clut_size = 0x10000UL }
	CLUT entry count (16-bit address space). More...
enum	ra8_glcdc_priv_const_t : 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 }
enum	ra8_glcdc_clut_const_t : uint16_t { k_ra8_glcdc_clut_entries = 256U }
enum	ra8_glcdc_priv_mask_t : uint32_t { k_ra8_glcdc_clutsel_mask = 0x10000UL , k_ra8_glcdc_arcon_mask = 0x1000UL }
enum	: uintptr_t { k_addr_prcr = 0x4001E3FAUL , k_addr_pdctrgd = 0x4001E110UL , k_addr_lcdckdivcr = 0x4001E05EUL , k_addr_lcdckcr = 0x4001E05FUL , k_addr_hococr = 0x4001E036UL }
	Power on the GLCDC graphics power domain and route LCDCLK. More...
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 }
enum	ra8_glcdc_layout_priv_t : 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 }
enum	ra8_glcdc_tcon_sel_t : uint32_t { k_glcdc_sel_stva = 0U , k_glcdc_sel_stvb = 1U , k_glcdc_sel_stha = 2U , k_glcdc_sel_de = 7U }
enum	ra8_glcdc_dispsel_priv_t : uint32_t { k_glcdc_dispsel_transparent = 1U , k_glcdc_dispsel_non_transparent = 2U }
enum	ra8_glcdc_alpha_priv_t : uint32_t { k_glcdc_alpha_opaque = 0xFFUL }
enum	ra8_glcdc_out_set_fmt_t : uint32_t { k_glcdc_out_set_rgb888 = 0U , k_glcdc_out_set_rgb666 = 1U , k_glcdc_out_set_rgb565 = 2U }
enum	ra8_glcdc_pdtha_fmt_t : uint32_t { k_glcdc_pdtha_rgb888 = 0U , k_glcdc_pdtha_rgb666 = 1U , k_glcdc_pdtha_rgb565 = 2U }

Functions
static void	internal_hoco_enable (void)
	Enable HOCO via PRC0-protected HOCOCR.
static void	internal_graphics_domain_power_on (void)
	Power on the Graphics power domain via PRC1-protected PDCTRGD.
static void	internal_lcdclk_switch_pll1r (void)
	Switch LCDCLK source to PLL1R / 4 via the SREQ/SRDY handshake.
static void	internal_graphics_power_on (void)
	Bring up the GLCDC graphics power domain and clock tree.
static void	internal_program_tcon (const ra8_glcdc_panel_timing_t *t)
	Program TCON sync-signal registers for parallel-RGB output.
static void	internal_program_bg (const ra8_glcdc_panel_timing_t *t)
	Program the GLCDC background-plane registers.
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)
	Program graphics layer 1 (top blend layer).
static void	internal_program_gr2 (const ra8_glcdc_panel_timing_t *t)
	Program graphics layer 2 (lower blend layer).
static void	internal_program_out (void)
	Program the OUT stage (output format, brightness, contrast).
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)
	Program every GLCDC register required to drive the panel.
ra8_err_t	ra8_glcdc_init (const ra8_glcdc_config_t *cfg)
	Initialise GLCDC with the EK-RA8D2 1024x600 timings and the supplied graphics layer 1 framebuffer.
ra8_err_t	ra8_glcdc_start (bool enable)
	Start or stop the panel output.
ra8_err_t	ra8_glcdc_set_dithering (ra8_glcdc_dither_mode_t mode)
	Programme the output dithering mode (PDTHA.SEL).
ra8_err_t	ra8_glcdc_set_brightness (uint8_t r, uint8_t g, uint8_t b)
	Programme per-channel output brightness.
ra8_err_t	ra8_glcdc_set_contrast (uint8_t r, uint8_t g, uint8_t b)
	Programme per-channel output contrast gain.
ra8_err_t	ra8_glcdc_deinit (void)
	Tear down GLCDC (stop + MSTP release).
ra8_err_t	ra8_glcdc_get_status (uint32_t *out_mask)
	Read GLCDC status register (VSYNC/HSYNC/underflow).
ra8_err_t	ra8_glcdc_clear_status (uint32_t mask)
	Clear GLCDC status flags.
ra8_err_t	ra8_glcdc_attach_handler (ra8_glcdc_event_fn_t fn, void *ctx)
	Attach a GLCDC event callback.
void	ra8_glcdc_dispatch (void)
	Dispatch a GLCDC event – snapshot + fire callback.
ra8_err_t	ra8_glcdc_enter_stop (void)
	Put GLCDC into MSTP-gated stop.
ra8_err_t	ra8_glcdc_exit_stop (void)
	Exit MSTP-gated stop.

Variables
static const char *	s_tag = "GLCDC"
static ra8_glcdc_event_fn_t	s_glcdc_fn
static void *	s_glcdc_ctx

Detailed Description

Graphics LCD Controller driver implementation.

Tag: [Ring 3 / HAL] {World: NS}

Driver for the RA8D2 GLCDC block. Programmes the background stage, both graphics layers (UI overlay over background image), the alpha blender, output-stage brightness/contrast/dithering, and double-buffered CLUTs. Closely mirrors the init order in FSP's r_glcdc_graphics_layer_set and the shadow-CLUT swap pattern in FSP's R_GLCDC_ClutEdit / R_GLCDC_ColorPaletteUpdate. Every register access carries a HUM Ch 63 citation.

Parameters

[in] mode See header declaration for direction and constraints.

Returns: ra8_err_t error code (or void if the signature returns void).

Return values

k_ra8_ok	Success path.
k_ra8_err_invalid_arg	Caller violated a precondition.

Precondition: Driver state has been initialized by the matching *_init.; Caller has validated all pointer parameters.

Postcondition: Side effects are limited to those documented in the header.; No global state is modified on the error path.

Note: Thread safety: see the header declaration.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Parameters

[in]	layer	See header declaration for direction and constraints.
[in]	plane	See header declaration for direction and constraints.
[in]	argb	See header declaration for direction and constraints.
[in]	global_alpha	See header declaration for direction and constraints.
[in]	cfg	See header declaration for direction and constraints.

Definition in file ra8_glcdc.c.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum : uintptr_t

Power on the GLCDC graphics power domain and route LCDCLK.

Unlocks PRCR (PRC0 for CGC, PRC1 for LPM), clears PDCTRGD to power on the Graphics domain, waits for PDPGSF status, then switches LCDCKCR to PLL1R via the SREQ / SRDY handshake and enables HOCO. Required once at boot before any GLCDC register is touched – the peripheral bus returns garbage until PDCTRGD clears.

Precondition: PRCR is currently locked (default reset state).; PLL1 has been brought up by ra8_cgc_init so PLL1R is available as a source for LCDCKCR.

Postcondition: PDCTRGD = 0 (Graphics domain powered).; LCDCKCR is sourcing LCDCLK from PLL1R / 4.

Note: Single-threaded init context; not safe to call from IRQ.

Since: 0.1.0

Enumerator
k_addr_prcr	Address prcr.
k_addr_pdctrgd	Address pdctrgd.
k_addr_lcdckdivcr	Address lcdckdivcr.
k_addr_lcdckcr	Address lcdckcr.
k_addr_hococr	Address hococr.

Definition at line 128 of file ra8_glcdc.c.

◆ anonymous enum

anonymous enum : uint16_t

Enumerator
k_prcr_unlock_lpm	Prcr unlock lpm.
k_prcr_unlock_cgc	Prcr unlock cgc.
k_prcr_relock	Prcr relock.

Definition at line 135 of file ra8_glcdc.c.

◆ anonymous enum

anonymous enum : uint8_t

Enumerator
k_pdctrgd_on	Pdctrgd on.
k_pdctrgd_pdcsf	bit 6: control-in-progress status.
k_pdctrgd_pdpgsf	bit 7: gated status.
k_pdctrgd_status	both status bits.
k_lcdck_sreq	Lcdck sreq.
k_lcdck_srdy_mask	Lcdck srdy mask.
k_lcdck_sel_pll1r	HUM 9.2.58 LCDCKSEL[3:0] = 1000b.
k_lcdckdivcr_div4	LCDCLK = PLL1R / 4 = 100 MHz.
k_hococr_run	Hococr run.

Definition at line 140 of file ra8_glcdc.c.

◆ glcdc_clut_t

enum glcdc_clut_t : uint32_t

CLUT entry count (16-bit address space).

Enumerator
k_glcdc_clut_size	GLCDC CLUT size.

Definition at line 62 of file ra8_glcdc.c.

◆ ra8_glcdc_alpha_priv_t

enum ra8_glcdc_alpha_priv_t : uint32_t

Enumerator
k_glcdc_alpha_opaque	Fully opaque (constant alpha).

Definition at line 365 of file ra8_glcdc.c.

◆ ra8_glcdc_clut_const_t

enum ra8_glcdc_clut_const_t : uint16_t

Enumerator
k_ra8_glcdc_clut_entries	Entries per CLUT plane.

Definition at line 79 of file ra8_glcdc.c.

◆ ra8_glcdc_dispsel_priv_t

enum ra8_glcdc_dispsel_priv_t : uint32_t

Enumerator
k_glcdc_dispsel_transparent	GLCDC dispsel transparent.
k_glcdc_dispsel_non_transparent	GLCDC dispsel non transparent.

Definition at line 359 of file ra8_glcdc.c.

◆ ra8_glcdc_layout_priv_t

enum ra8_glcdc_layout_priv_t : uint32_t

Enumerator
k_glcdc_shift_high	GLCDC shift high.
k_glcdc_shift_flm6_fmt	GLCDC shift flm6 fmt.
k_glcdc_shift_outset_fmt	GLCDC shift outset fmt.
k_glcdc_shift_pdtha_fmt	GLCDC shift pdtha fmt.
k_glcdc_shift_arcdef	GLCDC shift arcdef.
k_glcdc_axi_burst_bytes	GLCDC axi burst bytes.
k_glcdc_bpp_rgb565	GLCDC bpp rgb565.
k_glcdc_sync_pos_min	HUM 63 BG_SYNC.HP / VP min = 1.

Definition at line 337 of file ra8_glcdc.c.

◆ ra8_glcdc_out_set_fmt_t

enum ra8_glcdc_out_set_fmt_t : uint32_t

Enumerator
k_glcdc_out_set_rgb888	GLCDC out set rgb888.
k_glcdc_out_set_rgb666	GLCDC out set rgb666.
k_glcdc_out_set_rgb565	GLCDC out set rgb565.

Definition at line 375 of file ra8_glcdc.c.

◆ ra8_glcdc_pdtha_fmt_t

enum ra8_glcdc_pdtha_fmt_t : uint32_t

Enumerator
k_glcdc_pdtha_rgb888	GLCDC pdtha rgb888.
k_glcdc_pdtha_rgb666	GLCDC pdtha rgb666.
k_glcdc_pdtha_rgb565	GLCDC pdtha rgb565.

Definition at line 382 of file ra8_glcdc.c.

◆ ra8_glcdc_priv_const_t

enum ra8_glcdc_priv_const_t : uint8_t

Enumerator
k_ra8_glcdc_layer_count	Number of graphics layers.
k_ra8_glcdc_layer1	Layer index for GR[0].
k_ra8_glcdc_dispsel_below	AB1.DISPSEL = lower layer.
k_ra8_glcdc_dispsel_above	AB1.DISPSEL = upper layer.
k_ra8_glcdc_arcdef_shift	AB7.ARCDEF bit shift.
k_ra8_glcdc_clutsel_shift	CLUTINT.SEL bit position.
k_ra8_glcdc_pdtha_shift	PDTHA.SEL bit shift.
k_ra8_glcdc_word_shift	16-bit field shift.
k_ra8_glcdc_g_shift	Green-channel byte shift.
k_ra8_glcdc_b_shift	Blue-channel byte shift.

Definition at line 66 of file ra8_glcdc.c.

◆ ra8_glcdc_priv_mask_t

enum ra8_glcdc_priv_mask_t : uint32_t

Enumerator
k_ra8_glcdc_clutsel_mask	CLUTINT.SEL bit mask.
k_ra8_glcdc_arcon_mask	AB1.ARCON bit mask.

Definition at line 83 of file ra8_glcdc.c.

◆ ra8_glcdc_tcon_sel_t

enum ra8_glcdc_tcon_sel_t : uint32_t

Enumerator
k_glcdc_sel_stva	GLCDC sel stva.
k_glcdc_sel_stvb	GLCDC sel stvb.
k_glcdc_sel_stha	GLCDC sel stha.
k_glcdc_sel_de	GLCDC sel de.

Definition at line 349 of file ra8_glcdc.c.

Function Documentation

◆ internal_graphics_domain_power_on()

void internal_graphics_domain_power_on ( void )

static

Power on the Graphics power domain via PRC1-protected PDCTRGD.

HUM Ch 11.2.16 PDCTRGD power-on sequence (mirrors FSP bsp_clock_init):

wait PDCTRGD status == PDPGSF (fully gated, idle)
write PDCTRGD = 0 (PDDE = 0 -> request power on)
wait PDCTRGD status == 0 (fully on, transition complete) Skipping the second wait races the power-up transition and makes downstream MMIO writes vanish silently.

Precondition: PRCR is currently relocked.; HOCO has been re-enabled by internal_hoco_enable().

Postcondition: Graphics power domain is fully on.; PRCR is relocked.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 198 of file ra8_glcdc.c.

References k_addr_pdctrgd, k_addr_prcr, k_glcdc_clut_size, k_pdctrgd_on, k_pdctrgd_pdpgsf, k_pdctrgd_status, k_prcr_relock, and k_prcr_unlock_lpm.

Referenced by internal_graphics_power_on().

◆ internal_graphics_power_on()

void internal_graphics_power_on ( void )

static

Bring up the GLCDC graphics power domain and clock tree.

Orchestrates the three-step sequence required before any GLCDC register outside of MSTPCRC is writable on RA8D2:

internal_hoco_enable() – analogue trim clock
internal_graphics_domain_power_on()– PDCTRGD power-on
internal_lcdclk_switch_pll1r() – LCDCKCR -> PLL1R / 4 Runs on every build: the raw SYSC addresses fall inside the host test's fake-mmap peripheral window and the status polls consult the ra8_fake_mmio seam, so the real sequence executes on host too.

Precondition: Caller is in single-threaded init context with IRQs masked or not yet enabled.; PLL1 is running and PLL1R is a valid LCDCLK source (HUM 9.2.58).

Postcondition: Graphics power domain is fully on (PDCTRGD status == 0).; LCDCKCR.LCDCKSEL = PLL1R, LCDCKDIVCR = /4, PRCR relocked.

Note: Not thread-safe; touches CGC + LPM MMIO under PRC0/PRC1 unlocks.

Since: 0.1.0

Definition at line 311 of file ra8_glcdc.c.

References internal_graphics_domain_power_on(), internal_hoco_enable(), and internal_lcdclk_switch_pll1r().

Referenced by ra8_glcdc_init().

◆ internal_hoco_enable()

void internal_hoco_enable ( void )

static

Enable HOCO via PRC0-protected HOCOCR.

HUM Ch 9.2.34 HOCOCR.HCSTP = 0 starts the HOCO. FSP bsp_clock_init keeps HOCO enabled even on PLL1-sourced systems because the graphics power domain's analogue trim logic still requires it.

Precondition: PRCR is locked (default reset state).; Caller is in single-threaded init context.

Postcondition: HOCOCR.HCSTP = 0 (HOCO running).; PRCR is relocked.

Note: Not thread-safe; touches CGC MMIO under PRC0 unlock.

Since: 0.1.0

Definition at line 169 of file ra8_glcdc.c.

References k_addr_hococr, k_addr_prcr, k_hococr_run, k_prcr_relock, and k_prcr_unlock_cgc.

Referenced by internal_graphics_power_on().

◆ internal_lcdclk_switch_pll1r()

void internal_lcdclk_switch_pll1r ( void )

static

Switch LCDCLK source to PLL1R / 4 via the SREQ/SRDY handshake.

HUM Ch 9.2.58 LCDCKCR change handshake: SREQ=1 -> wait SRDY=1 -> set LCDCKDIVCR -> set LCDCKSEL with SREQ=1 -> drop SREQ -> wait SRDY=0. PRC0 (CGC) gates these writes.

Precondition: Graphics power domain is on.; PLL1 is running and PLL1R is a valid LCDCLK source.

Postcondition: LCDCKCR.LCDCKSEL = PLL1R; LCDCKDIVCR = /4 (100 MHz).; PRCR is relocked.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 251 of file ra8_glcdc.c.

References k_addr_lcdckcr, k_addr_lcdckdivcr, k_addr_prcr, k_glcdc_clut_size, k_lcdck_sel_pll1r, k_lcdck_srdy_mask, k_lcdck_sreq, k_lcdckdivcr_div4, k_prcr_relock, and k_prcr_unlock_cgc.

Referenced by internal_graphics_power_on().

◆ internal_panel_program()

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 )

static

Program every GLCDC register required to drive the panel.

Thin orchestrator that builds the panel-timing struct from the caller-supplied tm and calls the five per-stage helpers in the order FSP's r_glcdc_open uses: TCON, BG, GR1, GR2, OUT.

Parameters

[in]	fb_addr	Framebuffer base address for GR1.
[in]	fb_format	GR1 framebuffer pixel format.
[in]	fb_w	GR1 framebuffer width (pixels).
[in]	fb_h	GR1 framebuffer height (pixels).
[in]	tm	Panel RGB timing (from the board BSP).

Precondition: internal_graphics_power_on has been called.; GLCDC peripheral clock is active (MSTPCRD enabled).

Postcondition: All GLCDC stage shadow registers are programmed.; Pipeline is configured for BG-only output until a caller flips GR1.FLMRD=1 with a populated framebuffer.

Note: Single-threaded init context only.

Since: 0.1.0

Definition at line 636 of file ra8_glcdc.c.

References ra8_glcdc_timing_t::h_active, ra8_glcdc_timing_t::h_back, ra8_glcdc_timing_t::h_front, ra8_glcdc_timing_t::h_sync, internal_program_bg(), internal_program_gr1(), internal_program_gr2(), internal_program_out(), internal_program_tcon(), ra8_glcdc_timing_t::v_active, ra8_glcdc_timing_t::v_back, ra8_glcdc_timing_t::v_front, and ra8_glcdc_timing_t::v_sync.

Referenced by ra8_glcdc_init().

◆ internal_program_bg()

void internal_program_bg ( const ra8_glcdc_panel_timing_t * t )

static

Program the GLCDC background-plane registers.

Sets BG period, sync position, and active area so the BG plane drives a full-frame solid colour from BG_BGC. Mirrors FSP r_glcdc_background_screen_set.

Parameters

[in] t Panel timing parameters used to compute the BG area and frame period.

Precondition: internal_program_tcon has been called.; GLCDC is held in SWRST so writes go to shadow registers.

Postcondition: BG plane is programmed for t->h_active x t->v_active.; BG_BGC is cleared to zero (callers set it via ra8_glcdc_set_background_color).

Note: Single-threaded init context only.

Since: 0.1.0

Definition at line 471 of file ra8_glcdc.c.

References ra8_glcdc_panel_timing_t::h_active, ra8_glcdc_panel_timing_t::h_back, ra8_glcdc_panel_timing_t::h_total, k_glcdc_shift_high, k_glcdc_sync_pos_min, k_ra8_glcdc_off_bg_bgc, k_ra8_glcdc_off_bg_hsize, k_ra8_glcdc_off_bg_per, k_ra8_glcdc_off_bg_sync, k_ra8_glcdc_off_bg_vsize, ra8_glcdc_reg32(), ra8_glcdc_panel_timing_t::v_active, ra8_glcdc_panel_timing_t::v_back, and ra8_glcdc_panel_timing_t::v_total.

Referenced by internal_panel_program().

◆ internal_program_gr1()

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 )

static

Program graphics layer 1 (top blend layer).

Configures GR1's framebuffer pointer, format, AXI burst count, panel position/size, and alpha. DISPSEL=transparent and FLMRD=0 so by default GR1 contributes nothing to the output – callers that want layer-1 pixels fill the framebuffer themselves and flip FLMRD=1.

Parameters

[in]	t	Panel timing.
[in]	fb_addr	GR1 framebuffer base address.
[in]	fb_format	Pixel format code for FLM6.FORMAT[30:28].
[in]	fb_w	Framebuffer width in pixels (and layer width on the panel).
[in]	fb_h	Framebuffer height in pixels (and layer height on the panel).

Precondition: internal_program_bg has been called.; fb_addr points to allocated framebuffer memory (only accessed once FLMRD is flipped to 1 by the caller).

Postcondition: GR1 is hidden (DISPSEL=transparent, FLMRD=0, alpha=0).; All other GR1 registers are programmed for full-panel layer dimensions.

Note: Single-threaded init context only.

Since: 0.1.0

Definition at line 509 of file ra8_glcdc.c.

References ra8_glcdc_panel_timing_t::h_back, k_glcdc_axi_burst_bytes, k_glcdc_bpp_rgb565, k_glcdc_dispsel_transparent, k_glcdc_shift_flm6_fmt, k_glcdc_shift_high, k_ra8_glcdc_off_gr1_ab1, k_ra8_glcdc_off_gr1_ab2, k_ra8_glcdc_off_gr1_ab4, k_ra8_glcdc_off_gr1_ab5, k_ra8_glcdc_off_gr1_ab7, k_ra8_glcdc_off_gr1_flm3, k_ra8_glcdc_off_gr1_flmrd, k_ra8_glcdc_off_gr1_fmt, k_ra8_glcdc_off_gr1_line, k_ra8_glcdc_off_gr1_saddr, k_ra8_glcdc_off_gr1_size, ra8_glcdc_reg32(), and ra8_glcdc_panel_timing_t::v_back.

Referenced by internal_panel_program().

◆ internal_program_gr2()

void internal_program_gr2 ( const ra8_glcdc_panel_timing_t * t )

static

Program graphics layer 2 (lower blend layer).

CRITICAL bring-up finding (2026-05-10): the RA8D2 GLCDC output stage composes its final pixel from BG x GR2 x GR1. If GR2 is left in reset state (all zeros, FLMRD=0, AB1.DISPSEL=0), the pipeline emits solid black even when BG_BGC is non-zero and GR1.DISPSEL=transparent – the unconfigured lower layer silently masks the BG plane. This helper configures GR2 to the same dimensions as the panel with DISPSEL=transparent, alpha=0, and FLMRD=0, so it occupies its pipeline slot without contributing pixels. Mirrors FSP r_glcdc_open which configures both layers in a for (layer = 0..1) loop.

Parameters

[in] t Panel timing parameters used for GR2 dimensions.

Precondition: internal_program_gr1 has been called.; GLCDC is held in SWRST so writes go to shadow registers.

Postcondition: GR2 is hidden (DISPSEL=transparent, FLMRD=0, alpha=0) but its pipeline slot is configured.; ra8_glcdc_start must still assert GR2.VEN to commit.

Note: Single-threaded init context only.

Since: 0.1.0

Definition at line 568 of file ra8_glcdc.c.

References ra8_glcdc_panel_timing_t::h_active, ra8_glcdc_panel_timing_t::h_back, k_glcdc_dispsel_transparent, k_glcdc_shift_high, k_ra8_glcdc_off_gr2_ab1, k_ra8_glcdc_off_gr2_ab2, k_ra8_glcdc_off_gr2_ab4, k_ra8_glcdc_off_gr2_ab5, k_ra8_glcdc_off_gr2_ab7, k_ra8_glcdc_off_gr2_flmrd, k_ra8_glcdc_off_gr2_size, ra8_glcdc_reg32(), ra8_glcdc_panel_timing_t::v_active, and ra8_glcdc_panel_timing_t::v_back.

Referenced by internal_panel_program().

◆ internal_program_out()

void internal_program_out ( void )

static

Program the OUT stage (output format, brightness, contrast).

Selects RGB888 output (drives all 24 LCD_DATAn pins; the chip auto-expands RGB565 framebuffer pixels internally) and programs identity brightness/contrast. Mirrors FSP r_glcdc_output_block_set + the default brightness/contrast path in r_glcdc_brightness_correction.

Precondition: internal_program_gr2 has been called.; GLCDC is held in SWRST so writes go to shadow registers.

Postcondition: Output bus format is RGB888 to match the parallel-RGB panel.; Brightness/contrast are configured for identity transform.

Note: Single-threaded init context only.

Since: 0.1.0

< Bright mid.

< Contrast mid.

Definition at line 597 of file ra8_glcdc.c.

References k_glcdc_out_set_rgb888, k_glcdc_pdtha_rgb888, k_glcdc_shift_outset_fmt, k_glcdc_shift_pdtha_fmt, k_ra8_glcdc_off_out_bright1, k_ra8_glcdc_off_out_bright2, k_ra8_glcdc_off_out_contrast, k_ra8_glcdc_off_out_set, k_ra8_glcdc_off_panel_dtha, and ra8_glcdc_reg32().

Referenced by internal_panel_program().

◆ internal_program_tcon()

void internal_program_tcon ( const ra8_glcdc_panel_timing_t * t )

static

Program TCON sync-signal registers for parallel-RGB output.

Sets STVA/STHA pulse widths and routes STVA -> TCON0, STHA -> TCON1, DE -> TCON2 with the polarity inversions that the panel expects. Mirrors FSP r_glcdc_sync_signal_set.

Parameters

[in] t Panel timing parameters; only h_* and v_* widths and the back-porch values are read.

Precondition: internal_graphics_power_on has been called.; GLCDC is held in SWRST so writes go to shadow registers.

Postcondition: TCON shadow registers contain the panel's sync timing.; TCON.DE polarity is set to active-high.

Note: Single-threaded init context only.

Since: 0.1.0

Definition at line 426 of file ra8_glcdc.c.

References ra8_glcdc_panel_timing_t::h_active, ra8_glcdc_panel_timing_t::h_back, ra8_glcdc_panel_timing_t::h_sync, k_glcdc_sel_de, k_glcdc_sel_stha, k_glcdc_sel_stva, k_glcdc_shift_high, k_ra8_glcdc_off_out_clkphase, k_ra8_glcdc_off_tcon_de, k_ra8_glcdc_off_tcon_stha1, k_ra8_glcdc_off_tcon_stha2, k_ra8_glcdc_off_tcon_sthb1, k_ra8_glcdc_off_tcon_sthb2, k_ra8_glcdc_off_tcon_stva1, k_ra8_glcdc_off_tcon_stva2, k_ra8_glcdc_off_tcon_stvb1, k_ra8_glcdc_off_tcon_stvb2, k_ra8_glcdc_off_tcon_tim, ra8_glcdc_reg32(), ra8_glcdc_panel_timing_t::v_active, ra8_glcdc_panel_timing_t::v_back, and ra8_glcdc_panel_timing_t::v_sync.

Referenced by internal_panel_program().

◆ ra8_glcdc_attach_handler()

ra8_err_t ra8_glcdc_attach_handler	(	ra8_glcdc_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach a GLCDC event callback.

Since: 0.1.0

Definition at line 842 of file ra8_glcdc.c.

References k_ra8_ok, s_glcdc_ctx, and s_glcdc_fn.

◆ ra8_glcdc_clear_status()

ra8_err_t ra8_glcdc_clear_status ( uint32_t mask )

nodiscard

Clear GLCDC status flags.

Since: 0.1.0

Definition at line 835 of file ra8_glcdc.c.

References k_ra8_glcdc_off_sys_stat, k_ra8_ok, and ra8_glcdc_reg32().

◆ ra8_glcdc_deinit()

ra8_err_t ra8_glcdc_deinit ( void )

nodiscard

Tear down GLCDC (stop + MSTP release).

Since: 0.1.0

Definition at line 818 of file ra8_glcdc.c.

References k_ra8_glcdc_off_bg_en, k_ra8_glcdc_off_gr1_en, k_ra8_glcdc_off_sys_cfg, k_ra8_mstp_glcdc, ra8_glcdc_reg32(), ra8_mstp_disable(), s_glcdc_ctx, and s_glcdc_fn.

Referenced by internal_lcd_deinit().

◆ ra8_glcdc_dispatch()

void ra8_glcdc_dispatch ( void )

Dispatch a GLCDC event – snapshot + fire callback.

Since: 0.1.0

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Precondition: Driver state has been initialized by the matching *_init.; Caller has validated all pointer parameters.

Postcondition: Side effects are limited to those documented in the header.; No global state is modified on the error path.

Note: Thread safety: see the header declaration.

Definition at line 850 of file ra8_glcdc.c.

References k_ra8_glcdc_off_sys_stat, ra8_glcdc_reg32(), s_glcdc_ctx, and s_glcdc_fn.

◆ ra8_glcdc_enter_stop()

ra8_err_t ra8_glcdc_enter_stop ( void )

nodiscard

Put GLCDC into MSTP-gated stop.

Since: 0.1.0

Definition at line 862 of file ra8_glcdc.c.

References k_ra8_glcdc_off_sys_cfg, k_ra8_mstp_glcdc, ra8_glcdc_reg32(), and ra8_mstp_disable().

◆ ra8_glcdc_exit_stop()

ra8_err_t ra8_glcdc_exit_stop ( void )

nodiscard

Exit MSTP-gated stop.

Since: 0.1.0

Definition at line 868 of file ra8_glcdc.c.

References k_ra8_mstp_glcdc, and ra8_mstp_enable().

◆ ra8_glcdc_get_status()

ra8_err_t ra8_glcdc_get_status ( uint32_t * out_mask )

nodiscard

Read GLCDC status register (VSYNC/HSYNC/underflow).

Since: 0.1.0

Definition at line 828 of file ra8_glcdc.c.

References k_ra8_glcdc_off_sys_stat, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_glcdc_reg32(), and s_tag.

Referenced by gh_glcdc_programmed().

◆ ra8_glcdc_init()

ra8_err_t ra8_glcdc_init ( const ra8_glcdc_config_t * cfg )

nodiscard

Initialise GLCDC with the EK-RA8D2 1024x600 timings and the supplied graphics layer 1 framebuffer.

Since: 0.1.0

< Panel clk clksel lcdclk.

< Panel clk clken.

< Panel clk dcdr div2.

Definition at line 662 of file ra8_glcdc.c.

References ra8_glcdc_config_t::format, ra8_glcdc_config_t::framebuffer_addr, ra8_glcdc_config_t::height_px, internal_graphics_power_on(), internal_panel_program(), k_ra8_glcdc_off_bg_en, k_ra8_glcdc_off_panel_clk, k_ra8_mstp_glcdc, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_glcdc_reg32(), ra8_log_info_val, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, s_tag, ra8_glcdc_config_t::timing, and ra8_glcdc_config_t::width_px.

Referenced by internal_lcd_bringup_panel(), internal_lcd_bringup_panel(), and ra8_nsc_glcdc_init().

◆ ra8_glcdc_set_brightness()

ra8_err_t ra8_glcdc_set_brightness	(	uint8_t	r,
		uint8_t	g,
		uint8_t	b )

nodiscard

Programme per-channel output brightness.

Writes g to BRIGHT1.BRTG and packs b/r into BRIGHT2.BRTB/BRTR. The values are 8-bit offsets that are added to the 10-bit channel (the low bits of the 10-bit BRTx field are left as 0 – callers wanting the full range supply pre-scaled numbers in the 0..255 portion).

Parameters

[in]	r	Red brightness offset (0..255).
[in]	g	Green brightness offset (0..255).
[in]	b	Blue brightness offset (0..255).

Returns: ra8_err_t

Return values

k_ra8_ok Always.

Since: 0.1.0

Definition at line 791 of file ra8_glcdc.c.

References k_ra8_glcdc_off_out_bright1, k_ra8_glcdc_off_out_bright2, k_ra8_glcdc_word_shift, k_ra8_ok, and ra8_glcdc_reg32().

◆ ra8_glcdc_set_contrast()

ra8_err_t ra8_glcdc_set_contrast	(	uint8_t	r,
		uint8_t	g,
		uint8_t	b )

nodiscard

Programme per-channel output contrast gain.

Writes the three 8-bit gains into CONTRAST.CONTG/CONTB/CONTR. 0x80 == x1.000 gain (FSP convention).

Parameters

[in]	r	Red contrast gain (0..255, 0x80 = 1.0).
[in]	g	Green contrast gain (0..255, 0x80 = 1.0).
[in]	b	Blue contrast gain (0..255, 0x80 = 1.0).

Returns: ra8_err_t

Return values

k_ra8_ok Always.

Since: 0.1.0

Definition at line 802 of file ra8_glcdc.c.

References k_ra8_glcdc_b_shift, k_ra8_glcdc_g_shift, k_ra8_glcdc_off_out_contrast, k_ra8_ok, and ra8_glcdc_reg32().

◆ ra8_glcdc_set_dithering()

ra8_err_t ra8_glcdc_set_dithering ( ra8_glcdc_dither_mode_t mode )

nodiscard

Programme the output dithering mode (PDTHA.SEL).

Selects the dithering algorithm applied when the 24bpp internal pipeline drives a narrower (18bpp / 16bpp) panel.

Parameters

[in] mode Dither mode.

Returns: ra8_err_t

Return values

k_ra8_ok	Dither register written.
k_ra8_err_invalid_arg	mode was out of range.

Since: 0.1.0

Definition at line 766 of file ra8_glcdc.c.

References k_ra8_dither_2x2, k_ra8_dither_off, k_ra8_dither_truncate, k_ra8_err_invalid_arg, k_ra8_glcdc_off_panel_dtha, k_ra8_glcdc_pdtha_shift, k_ra8_ok, and ra8_glcdc_reg32().

◆ ra8_glcdc_start()

ra8_err_t ra8_glcdc_start ( bool enable )

nodiscard

Start or stop the panel output.

Since: 0.1.0

< Bit en.

< Bit ven.

< Bit swrst.

Definition at line 709 of file ra8_glcdc.c.

References k_ra8_glcdc_off_bg_en, k_ra8_glcdc_off_gr1_en, k_ra8_glcdc_off_gr2_en, k_ra8_glcdc_off_out_vlatch, k_ra8_glcdc_off_sys_cfg, k_ra8_ok, and ra8_glcdc_reg32().

Referenced by internal_lcd_bringup_panel(), and internal_lcd_bringup_panel().

Variable Documentation

◆ s_glcdc_ctx

void* s_glcdc_ctx

static

Definition at line 816 of file ra8_glcdc.c.

Referenced by ra8_glcdc_attach_handler(), ra8_glcdc_deinit(), and ra8_glcdc_dispatch().

◆ s_glcdc_fn

ra8_glcdc_event_fn_t s_glcdc_fn

static

Definition at line 815 of file ra8_glcdc.c.

Referenced by ra8_glcdc_attach_handler(), ra8_glcdc_deinit(), and ra8_glcdc_dispatch().

◆ s_tag

const char* s_tag = "GLCDC"

static

Definition at line 54 of file ra8_glcdc.c.

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

◆ anonymous enum

◆ glcdc_clut_t

◆ ra8_glcdc_alpha_priv_t

◆ ra8_glcdc_clut_const_t

◆ ra8_glcdc_dispsel_priv_t

◆ ra8_glcdc_layout_priv_t

◆ ra8_glcdc_out_set_fmt_t

◆ ra8_glcdc_pdtha_fmt_t

◆ ra8_glcdc_priv_const_t

◆ ra8_glcdc_priv_mask_t

◆ ra8_glcdc_tcon_sel_t

Function Documentation

◆ internal_graphics_domain_power_on()

◆ internal_graphics_power_on()

◆ internal_hoco_enable()

◆ internal_lcdclk_switch_pll1r()

◆ internal_panel_program()

◆ internal_program_bg()

◆ internal_program_gr1()

◆ internal_program_gr2()

◆ internal_program_out()

◆ internal_program_tcon()

◆ ra8_glcdc_attach_handler()

◆ ra8_glcdc_clear_status()

◆ ra8_glcdc_deinit()

◆ ra8_glcdc_dispatch()

◆ ra8_glcdc_enter_stop()

◆ ra8_glcdc_exit_stop()

◆ ra8_glcdc_get_status()

◆ ra8_glcdc_init()

◆ ra8_glcdc_set_brightness()

◆ ra8_glcdc_set_contrast()

◆ ra8_glcdc_set_dithering()

◆ ra8_glcdc_start()

Variable Documentation

◆ s_glcdc_ctx

◆ s_glcdc_fn

◆ s_tag