MIPI D-PHY driver implementation. More...

#include "ra8_mipi_phy.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_mipi_phy_internal.h"
#include "ra8_mipi_phy_regs.h"
#include "ra8_mstp_regs.h"

Include dependency graph for ra8_mipi_phy.c:

Enumerations
enum	ra8_mipi_phy_limits_t : uint16_t { k_ra8_mipi_phy_pclka_min_mhz = 40U , k_ra8_mipi_phy_pclka_max_mhz = 125U , k_ra8_mipi_phy_escdiv_max = 31U , k_ra8_mipi_phy_nmul_min = 40U , k_ra8_mipi_phy_nmul_max = 375U , k_ra8_mipi_phy_spin_budget = 4096U }
	Validation guard rails for ra8_mipi_phy_init. More...
enum	ra8_mipi_phy_mstpc_bit_t : uint8_t { k_ra8_mipi_phy_mstpc_bit = 13U }
	Direct-write fallback for the MIPI PHY module-stop bit. More...
enum	ra8_mipi_phy_lane_bit_t : uint8_t { k_ra8_mipi_phy_lane_bit_clk = 0U , k_ra8_mipi_phy_lane_bit_d0 = 1U , k_ra8_mipi_phy_lane_bit_d1 = 2U }
	Software-lane bitmap positions for s_lane_enable_mask. More...
enum	ra8_mipi_phy_lane_mask_t : uint8_t { k_ra8_mipi_phy_lane_mask_default }
	Default lane-enable bitmap (clock + d0 + d1 all on). More...

Functions
static void	internal_mipi_phy_mstp_unstop (void)
	Clear MSTPCRC bit 13, ungating MIPI PHY.
static ra8_err_t	internal_mipi_phy_wait_set (volatile const uint32_t *reg, uint32_t mask)
static uint32_t	internal_mipi_phy_pack_plfcr (const ra8_mipi_phy_pll_t *pll)
static ra8_err_t	internal_mipi_phy_validate_pll (const ra8_mipi_phy_pll_t *pll)
	Validate a ra8_mipi_phy_pll_t against HUM 64.2.2 p 3823 limits.
void	priv_mipi_phy_write_timing (const ra8_mipi_phy_timing_t *t)
	Implementation of priv_mipi_phy_write_timing() – packs DPHYTIM1..6.
static ra8_err_t	internal_mipi_phy_validate_init_cfg (const ra8_mipi_phy_config_t *cfg)
	Validate ranges/lane-count for ra8_mipi_phy_init.
static ra8_err_t	internal_mipi_phy_init_power_up (const ra8_mipi_phy_config_t *cfg)
	Apply common init steps 1-5 (mode, refclk, LDO power-up).
static ra8_err_t	internal_mipi_phy_init_host (const ra8_mipi_phy_config_t *cfg)
	Apply DSI-host-only steps (6-9) of the init sequence.
static void	internal_mipi_phy_cache_state (const ra8_mipi_phy_config_t *cfg)
	Latch cfg knobs into the driver's tracked-state cache.
ra8_err_t	ra8_mipi_phy_init (const ra8_mipi_phy_config_t *cfg)
	Bring up the D-PHY end-to-end per HUM Ch 64.3.1 p 3837.
ra8_err_t	ra8_mipi_phy_deinit (void)
	Stop the D-PHY per HUM Ch 64.3.2 p 3837 (DPHYEN -> PLLSTP -> PWRSEN).
ra8_err_t	ra8_mipi_phy_reset (void)
	Reset the PHY to its post-MSTPCRC-clear state without re-init.
ra8_err_t	ra8_mipi_phy_recover_from_error (const ra8_mipi_phy_config_t *cfg)
	Reset and re-arm the PHY after an LDO drop / PLL unlock.
ra8_err_t	ra8_mipi_phy_get_status (uint32_t *out_mask)
	Read the D-PHY status flags (DPHYSFR).
bool	ra8_mipi_phy_is_ldo_stable (void)
	Test whether the LDO has stabilised (DPHYSFR.PWRSF = 1).
bool	ra8_mipi_phy_is_pll_locked (void)
	Test whether the PLL is locked (DPHYSFR.PLLSF = 1).
ra8_err_t	ra8_mipi_phy_wait_ready (void)
	Bounded poll until the PHY is fully ready (PWRSF & PLLSF).
ra8_err_t	ra8_mipi_phy_attach_handler (ra8_mipi_phy_event_fn_t fn, void *ctx)
	Attach a status callback fired by ra8_mipi_phy_dispatch.
void	ra8_mipi_phy_dispatch (void)
	Read DPHYSFR, snapshot it, decode events, and fire the callback.
ra8_err_t	ra8_mipi_phy_enter_stop (void)
	Pre-standby tear-down: disable D-PHY then drop the LDO.
ra8_err_t	ra8_mipi_phy_exit_stop (const ra8_mipi_phy_config_t *cfg)
	Post-standby resume: re-run the start-up procedure.
ra8_err_t	ra8_mipi_phy_ldo_enable (void)
	Enable the D-PHY LDO (DPHYPWRCR.PWRSEN = 1) only.
ra8_err_t	ra8_mipi_phy_ldo_disable (void)
	Disable the D-PHY LDO (DPHYPWRCR.PWRSEN = 0) only.
ra8_err_t	ra8_mipi_phy_pll_start (void)
	Release the PLL (DPHYPLOCR.PLLSTP = 0) and wait for lock.
ra8_err_t	ra8_mipi_phy_pll_stop (void)
	Stop the PLL (DPHYPLOCR.PLLSTP = 1).
ra8_err_t	ra8_mipi_phy_set_lane_speed (const ra8_mipi_phy_pll_t *pll)
	Reprogram the PLL coefficients (DPHYPLFCR) at runtime.
ra8_err_t	ra8_mipi_phy_switch_mode (ra8_mipi_phy_mode_t mode)
	Switch the PHY between DSI host and CSI device mode.
ra8_err_t	ra8_mipi_phy_set_lane_count (ra8_mipi_phy_lane_count_t count)
	Configure the active lane count.
ra8_mipi_phy_lane_count_t	ra8_mipi_phy_get_lane_count (void)
	Read back the lane count last configured.
ra8_err_t	ra8_mipi_phy_set_lane_enable (ra8_mipi_phy_lane_id_t lane, bool enable)
	Enable or disable a single data lane.
bool	ra8_mipi_phy_is_lane_enabled (ra8_mipi_phy_lane_id_t lane)
	Query whether the given lane is currently enabled.
ra8_err_t	ra8_mipi_phy_set_clock_mode (ra8_mipi_phy_clk_mode_t mode)
	Set the HS clock-lane mode (continuous vs non-continuous).
ra8_mipi_phy_clk_mode_t	ra8_mipi_phy_get_clock_mode (void)
	Query the HS clock-lane mode last configured.
ra8_err_t	ra8_mipi_phy_set_eotp (ra8_mipi_phy_eotp_t eotp)
	Set the EoTP packet emission preference (DSI host only).
ra8_mipi_phy_eotp_t	ra8_mipi_phy_get_eotp (void)
	Query the EoTP setting last configured.
ra8_err_t	ra8_mipi_phy_set_pclka_freq (uint8_t mhz)
	Update DPHYREFCR.RFREQ at runtime.
ra8_err_t	ra8_mipi_phy_set_escape_divisor (uint8_t escdiv)
	Update DPHYESCCR.ESCDIV at runtime.
ra8_err_t	ra8_mipi_phy_validate_pll_band (const ra8_mipi_phy_pll_t *pll, uint8_t mosc_mhz)
	Validate a PLL coefficient block against HUM 64.2.2 p 3823-3824.

Variables
static const char *	s_tag = "MIPI_PHY"
	Log tag for ra8_log_* calls in this driver.
static ra8_mipi_phy_event_fn_t	s_mipi_phy_fn
	Registered callback for ra8_mipi_phy_dispatch.
static void *	s_mipi_phy_ctx
	Opaque context forwarded to s_mipi_phy_fn.
static uint32_t	s_last_sfr
	Previous DPHYSFR snapshot, used for edge detection in dispatch.
static ra8_mipi_phy_lane_count_t	s_lane_count = k_ra8_mipi_phy_lane_count_2
	Last lane-count argument accepted by ra8_mipi_phy_set_lane_count.
static uint8_t	s_lane_enable_mask = k_ra8_mipi_phy_lane_mask_default
	Bitmap of enabled lanes (bit 0 = clock, bit N = data lane N-1).
static ra8_mipi_phy_clk_mode_t	s_clk_mode = k_ra8_mipi_phy_clk_noncontinuous
	HS clock-lane operating mode (continuous vs non-continuous).
static ra8_mipi_phy_eotp_t	s_eotp = k_ra8_mipi_phy_eotp_disabled
	Whether DSI host should append EoTP packets (host mode).

Detailed Description

MIPI D-PHY driver implementation.

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

Full HUM Ch 64 coverage (p 3822-3838). Every documented register field has a corresponding code path; every operating mode is reachable through the public API; every IRQ source is decoded by the dispatcher. The PHY is consumed by ra8_mipi_dsi (host) and ra8_mipi_csi (device); this driver does NOT touch either of those files.

Driver scope:

Lifecycle: init / deinit / reset / recover_from_error / enter_stop / exit_stop.
Power: ldo_enable / ldo_disable / pll_start / pll_stop.
Mode: switch_mode (DSI <-> CSI), set_clock_mode (continuous / non-continuous HS clock), set_eotp.
Lanes: set_lane_count (1/2 supported, 3/4 rejected), set_lane_enable per lane.
PLL re-tune: set_lane_speed, validate_pll_band.
Reference / escape: set_pclka_freq, set_escape_divisor.
Timing tables: select_timing – HUM Tables 64.2 (DSI) / 64.3 (CSI) p 3831-3836 are encoded as a static lookup table.
Status / IRQ: get_status / clear_status / is_pll_locked / is_ldo_stable / wait_ready / attach_handler / dispatch.

The dispatcher tracks the previous DPHYSFR snapshot so it can decode every documented status edge (PWRSF / PLLSF rising and falling) into a typed ra8_mipi_phy_event_t rather than handing the consumer a raw register dump.

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

Definition in file ra8_mipi_phy.c.

Enumeration Type Documentation

◆ ra8_mipi_phy_lane_bit_t

enum ra8_mipi_phy_lane_bit_t : uint8_t

Software-lane bitmap positions for s_lane_enable_mask.

Enumerator
k_ra8_mipi_phy_lane_bit_clk	bit 0: clock lane.
k_ra8_mipi_phy_lane_bit_d0	bit 1: data lane 0.
k_ra8_mipi_phy_lane_bit_d1	bit 2: data lane 1.

Definition at line 100 of file ra8_mipi_phy.c.

◆ ra8_mipi_phy_lane_mask_t

enum ra8_mipi_phy_lane_mask_t : uint8_t

Default lane-enable bitmap (clock + d0 + d1 all on).

Enumerator
k_ra8_mipi_phy_lane_mask_default	RA8 mipi PHY lane mask default.

Definition at line 110 of file ra8_mipi_phy.c.

◆ ra8_mipi_phy_limits_t

enum ra8_mipi_phy_limits_t : uint16_t

Validation guard rails for ra8_mipi_phy_init.

HUM Ch 64.2.1 p 3822: RFREQ accepts 0x27 (40 MHz) .. 0x7C (125 MHz). HUM Ch 64.2.4 p 3825: ESCDIV[4:0] is a 5-bit field. HUM Ch 64.2.2 p 3823: NMUL[8:0] valid range is 40 .. 375.

Enumerator
k_ra8_mipi_phy_pclka_min_mhz	Lower bound on RFREQ value.
k_ra8_mipi_phy_pclka_max_mhz	Upper bound on RFREQ value.
k_ra8_mipi_phy_escdiv_max	5-bit field width.
k_ra8_mipi_phy_nmul_min	NMUL_int floor.
k_ra8_mipi_phy_nmul_max	NMUL_int ceiling.
k_ra8_mipi_phy_spin_budget	Max poll iterations.

Definition at line 68 of file ra8_mipi_phy.c.

◆ ra8_mipi_phy_mstpc_bit_t

enum ra8_mipi_phy_mstpc_bit_t : uint8_t

Direct-write fallback for the MIPI PHY module-stop bit.

The shared ra8_mstp_t enum in libs/ra8_hal/inc/ra8_mstp_regs.h does NOT yet have a k_ra8_mipi_phy entry. Per the agent brief we must not extend that file from this driver. As a stop-gap, the driver clears MSTPCRC bit 13 (the MIPI PHY slot in MSTPCRC – HUM Ch 64.4.2 p 3838 references MSTPCRC for the block) directly.

TODO: When ra8_mstp_regs.h gains an explicit k_ra8_mstp_mipi_phy value (driven by HUM Ch 11.2.8 "MSTPCRC" p 446-447), replace the direct register write below with ra8_mstp_enable(k_ra8_mstp_mipi_phy).

Enumerator
k_ra8_mipi_phy_mstpc_bit	Provisional MSTPC slot.

Definition at line 92 of file ra8_mipi_phy.c.

Function Documentation

◆ internal_mipi_phy_cache_state()

void internal_mipi_phy_cache_state ( const ra8_mipi_phy_config_t * cfg )

static

Latch cfg knobs into the driver's tracked-state cache.

None of these settings live in PHY registers; downstream DSI / CSI drivers consult them after init returns.

Parameters

[in] cfg See declaration: const ra8_mipi_phy_config_t* cfg.

Precondition: Module/state preconditions hold (see function body).; Module/state preconditions hold (see function body).

Postcondition: Documented side effects are visible on success.; Documented side effects are visible on success.

Note: Internal helper. Not thread-safe; caller provides synchronisation.

Since: 0.1.0

Definition at line 423 of file ra8_mipi_phy.c.

References ra8_mipi_phy_config_t::clk_mode, ra8_mipi_phy_config_t::eotp, k_ra8_mipi_phy_lane_mask_default, k_ra8_mipi_phy_off_sfr, ra8_mipi_phy_config_t::lane_count, ra8_mipi_phy_reg32(), s_clk_mode, s_eotp, s_lane_count, s_lane_enable_mask, and s_last_sfr.

Referenced by ra8_mipi_phy_init().

◆ internal_mipi_phy_init_host()

ra8_err_t internal_mipi_phy_init_host ( const ra8_mipi_phy_config_t * cfg )

static

Apply DSI-host-only steps (6-9) of the init sequence.

Steps come from HUM Ch 64 p 3823-3826: program PLFCR, ESCCR, clear PLOCR, then poll DPHYSFR until PLLSF latches.

Parameters

[in] cfg See declaration: const ra8_mipi_phy_config_t* cfg.

Returns: ra8_err_t outcome (or scalar return value).

Return values

k_ra8_ok	Operation completed successfully.
other	Non-zero error code from the underlying operation.

Precondition: Module/state preconditions hold (see function body).; Module/state preconditions hold (see function body).

Postcondition: Documented side effects are visible on success.; Documented side effects are visible on success.

Note: Internal helper. Not thread-safe; caller provides synchronisation.

Since: 0.1.0

Definition at line 398 of file ra8_mipi_phy.c.

References ra8_mipi_phy_config_t::escdiv, internal_mipi_phy_pack_plfcr(), internal_mipi_phy_wait_set(), k_ra8_mipi_phy_esccr_escdiv_mask, k_ra8_mipi_phy_off_esccr, k_ra8_mipi_phy_off_plfcr, k_ra8_mipi_phy_off_plocr, k_ra8_mipi_phy_off_sfr, k_ra8_mipi_phy_sfr_pllsf, ra8_mipi_phy_config_t::pll, and ra8_mipi_phy_reg32().

Referenced by ra8_mipi_phy_init().

◆ internal_mipi_phy_init_power_up()

ra8_err_t internal_mipi_phy_init_power_up ( const ra8_mipi_phy_config_t * cfg )

static

Apply common init steps 1-5 (mode, refclk, LDO power-up).

Step 1 (HUM Ch 64.4.2 p 3838) ungates MSTPCRC. Step 2 (HUM Ch 64.2.14 p 3836) selects host vs device via DPHYMDC. Step 3 (HUM Ch 64.2.1 p 3822) programs DPHYREFCR. Step 4 (HUM Ch 64.2.5 p 3826) sets DPHYPWRCR.PWRSEN. Step 5 (HUM Ch 64.2.6 p 3826) polls DPHYSFR until PWRSF latches.

Parameters

[in] cfg See declaration: const ra8_mipi_phy_config_t* cfg.

Returns: ra8_err_t outcome (or scalar return value).

Return values

k_ra8_ok	Operation completed successfully.
other	Non-zero error code from the underlying operation.

Precondition: Module/state preconditions hold (see function body).; Module/state preconditions hold (see function body).

Postcondition: Documented side effects are visible on success.; Documented side effects are visible on success.

Note: Internal helper. Not thread-safe; caller provides synchronisation.

Since: 0.1.0

Definition at line 365 of file ra8_mipi_phy.c.

References internal_mipi_phy_mstp_unstop(), internal_mipi_phy_wait_set(), k_ra8_mipi_phy_mdc_hosten, k_ra8_mipi_phy_mode_dsi_host, k_ra8_mipi_phy_off_mdc, k_ra8_mipi_phy_off_pwrcr, k_ra8_mipi_phy_off_refcr, k_ra8_mipi_phy_off_sfr, k_ra8_mipi_phy_pwrcr_pwrsen, k_ra8_mipi_phy_refcr_rfreq_bias, k_ra8_mipi_phy_refcr_rfreq_mask, k_ra8_mipi_phy_sfr_pwrsf, ra8_mipi_phy_config_t::mode, ra8_mipi_phy_config_t::pclka_mhz, and ra8_mipi_phy_reg32().

Referenced by ra8_mipi_phy_init().

◆ internal_mipi_phy_mstp_unstop()

void internal_mipi_phy_mstp_unstop ( void )

static

Clear MSTPCRC bit 13, ungating MIPI PHY.

Stop-gap until ra8_mstp_t learns the MIPI PHY slot. Cites HUM Ch 64.4.2 p 3838 ("MIPI PHY operation can be disabled or enabled using Module Stop Control Register C (MSTPCRC). The MIPI PHY module is initially stopped after reset.").

Precondition: Caller has unlocked write protection on MSTPCRC if required.; Called from a single-threaded init context (or with IRQs masked).

Postcondition: MSTPCRC bit 13 is cleared and the MIPI PHY clock is running.; No other MSTPCRC bits are modified.

Note: Internal helper. Not thread-safe; caller provides synchronisation.

Since: 0.1.0

Definition at line 186 of file ra8_mipi_phy.c.

References k_ra8_mipi_phy_mstpc_bit, r_mstp_regs_t::MSTPCRC, and ra8_mstp().

Referenced by internal_mipi_phy_init_power_up().

◆ internal_mipi_phy_pack_plfcr()

uint32_t internal_mipi_phy_pack_plfcr ( const ra8_mipi_phy_pll_t * pll )

static

Definition at line 207 of file ra8_mipi_phy.c.

References ra8_mipi_phy_pll_t::idiv, k_ra8_mipi_phy_plfcr_mask_idiv, k_ra8_mipi_phy_plfcr_mask_nfmul, k_ra8_mipi_phy_plfcr_mask_nmul, k_ra8_mipi_phy_plfcr_mask_pmul, k_ra8_mipi_phy_plfcr_shift_idiv, k_ra8_mipi_phy_plfcr_shift_nfmul, k_ra8_mipi_phy_plfcr_shift_nmul, k_ra8_mipi_phy_plfcr_shift_pmul, ra8_mipi_phy_pll_t::nfmul, ra8_mipi_phy_pll_t::nmul_int, and ra8_mipi_phy_pll_t::pmul.

Referenced by internal_mipi_phy_init_host(), and ra8_mipi_phy_set_lane_speed().

◆ internal_mipi_phy_validate_init_cfg()

ra8_err_t internal_mipi_phy_validate_init_cfg ( const ra8_mipi_phy_config_t * cfg )

static

Validate ranges/lane-count for ra8_mipi_phy_init.

Cites HUM Ch 64.2.1 p 3822 (RFREQ range), Ch 64.2.4 p 3825 (ESCDIV width), Ch 64.1 p 3822 (lane-count support matrix), and Ch 64.2.2 p 3823 (PLL parameter range, host mode only). Also rejects nullptrs in cfg and cfg->p_timing.

Parameters

[in] cfg See declaration: const ra8_mipi_phy_config_t* cfg.

Returns: ra8_err_t outcome (or scalar return value).

Return values

k_ra8_ok	Operation completed successfully.
other	Non-zero error code from the underlying operation.

Precondition: Module/state preconditions hold (see function body).; Module/state preconditions hold (see function body).

Postcondition: Documented side effects are visible on success.; Documented side effects are visible on success.

Note: Internal helper. Not thread-safe; caller provides synchronisation.

Since: 0.1.0

Definition at line 319 of file ra8_mipi_phy.c.

References ra8_mipi_phy_config_t::escdiv, internal_mipi_phy_validate_pll(), k_ra8_err_invalid_arg, k_ra8_err_not_supported, k_ra8_err_null_ptr, k_ra8_mipi_phy_escdiv_max, k_ra8_mipi_phy_lane_count_1, k_ra8_mipi_phy_lane_count_2, k_ra8_mipi_phy_lane_count_3, k_ra8_mipi_phy_lane_count_4, k_ra8_mipi_phy_mode_dsi_host, k_ra8_mipi_phy_pclka_max_mhz, k_ra8_mipi_phy_pclka_min_mhz, k_ra8_ok, ra8_mipi_phy_config_t::lane_count, ra8_mipi_phy_config_t::mode, ra8_mipi_phy_config_t::p_timing, ra8_mipi_phy_config_t::pclka_mhz, and ra8_mipi_phy_config_t::pll.

Referenced by ra8_mipi_phy_init().

◆ internal_mipi_phy_validate_pll()

ra8_err_t internal_mipi_phy_validate_pll ( const ra8_mipi_phy_pll_t * pll )

static

Validate a ra8_mipi_phy_pll_t against HUM 64.2.2 p 3823 limits.

Range-checks NMUL[8:0] only. Use ra8_mipi_phy_validate_pll_band for the full PMUL band check.

Parameters

[in] pll See declaration: const ra8_mipi_phy_pll_t* pll.

Returns: ra8_err_t outcome (or scalar return value).

Return values

k_ra8_ok	Operation completed successfully.
other	Non-zero error code from the underlying operation.

Precondition: Module/state preconditions hold (see function body).; Module/state preconditions hold (see function body).

Postcondition: Documented side effects are visible on success.; Documented side effects are visible on success.

Note: Internal helper. Not thread-safe; caller provides synchronisation.

Since: 0.1.0

Definition at line 239 of file ra8_mipi_phy.c.

References k_ra8_err_invalid_arg, k_ra8_mipi_phy_nmul_max, k_ra8_mipi_phy_nmul_min, k_ra8_ok, and ra8_mipi_phy_pll_t::nmul_int.

Referenced by internal_mipi_phy_validate_init_cfg(), ra8_mipi_phy_set_lane_speed(), and ra8_mipi_phy_validate_pll_band().

◆ internal_mipi_phy_wait_set()

ra8_err_t internal_mipi_phy_wait_set	(	volatile const uint32_t *	reg,
		uint32_t	mask )

static

Definition at line 195 of file ra8_mipi_phy.c.

References k_ra8_err_hw_timeout, k_ra8_mipi_phy_spin_budget, and k_ra8_ok.

Referenced by internal_mipi_phy_init_host(), internal_mipi_phy_init_power_up(), ra8_mipi_phy_ldo_enable(), ra8_mipi_phy_pll_start(), ra8_mipi_phy_set_escape_divisor(), ra8_mipi_phy_set_lane_speed(), and ra8_mipi_phy_wait_ready().

◆ priv_mipi_phy_write_timing()

void priv_mipi_phy_write_timing ( const ra8_mipi_phy_timing_t * t )

Implementation of priv_mipi_phy_write_timing() – packs DPHYTIM1..6.

Write the six DPHYTIMx registers from the timing block.

Definition at line 248 of file ra8_mipi_phy.c.

References k_ra8_mipi_phy_off_tim1, k_ra8_mipi_phy_off_tim2, k_ra8_mipi_phy_off_tim3, k_ra8_mipi_phy_off_tim4, k_ra8_mipi_phy_off_tim5, k_ra8_mipi_phy_off_tim6, k_ra8_mipi_phy_tim1_tinit_mask, k_ra8_mipi_phy_tim6_tlpx_mask, k_ra8_mipi_phy_tim_byte_mask, k_ra8_mipi_phy_tim_shift_b0, k_ra8_mipi_phy_tim_shift_b1, k_ra8_mipi_phy_tim_shift_b2, k_ra8_mipi_phy_tim_shift_b3, ra8_mipi_phy_reg32(), ra8_mipi_phy_timing_t::tclkmiss, ra8_mipi_phy_timing_t::tclkpost, ra8_mipi_phy_timing_t::tclkpre, ra8_mipi_phy_timing_t::tclkprep, ra8_mipi_phy_timing_t::tclksett, ra8_mipi_phy_timing_t::tclktrl, ra8_mipi_phy_timing_t::tclkzero, ra8_mipi_phy_timing_t::thsexit, ra8_mipi_phy_timing_t::thsprep, ra8_mipi_phy_timing_t::thssett, ra8_mipi_phy_timing_t::thstrl, ra8_mipi_phy_timing_t::thszero, ra8_mipi_phy_timing_t::tinit, and ra8_mipi_phy_timing_t::tlpx.

Referenced by ra8_mipi_phy_init(), and ra8_mipi_phy_select_timing().

◆ ra8_mipi_phy_attach_handler()

ra8_err_t ra8_mipi_phy_attach_handler	(	ra8_mipi_phy_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach a status callback fired by ra8_mipi_phy_dispatch.

Parameters

[in]	fn	Callback. NULL detaches.
[in]	ctx	Opaque value forwarded to the callback.

Returns: k_ra8_ok always.

Precondition: – (NULL fn is the documented detach signal).

Postcondition: Subsequent ra8_mipi_phy_dispatch calls see fn / ctx.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 552 of file ra8_mipi_phy.c.

References k_ra8_ok, s_mipi_phy_ctx, and s_mipi_phy_fn.

◆ ra8_mipi_phy_deinit()

ra8_err_t ra8_mipi_phy_deinit ( void )

nodiscard

Stop the D-PHY per HUM Ch 64.3.2 p 3837 (DPHYEN -> PLLSTP -> PWRSEN).

Returns: ra8_err_t error code.

Return values

k_ra8_ok All three writes succeeded.

Precondition: ra8_mipi_phy_init was previously called or the block is already in its post-reset state (in which case the writes are idempotent no-ops).

Postcondition: DPHYOCR.DPHYEN and DPHYPWRCR.PWRSEN both read 0.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 467 of file ra8_mipi_phy.c.

References k_ra8_mipi_phy_off_ocr, k_ra8_mipi_phy_off_plocr, k_ra8_mipi_phy_off_pwrcr, k_ra8_mipi_phy_plocr_pllstp, k_ra8_ok, ra8_log_info, ra8_mipi_phy_reg32(), and s_tag.

Referenced by ra8_mipi_phy_enter_stop().

◆ ra8_mipi_phy_dispatch()

void ra8_mipi_phy_dispatch ( void )

Read DPHYSFR, snapshot it, decode events, and fire the callback.

The PHY itself does not raise an NVIC vector – DSI / CSI do. The DSI / CSI driver may forward its IRQ here so any consumer can observe LDO / PLL transitions through one common slot. This dispatcher compares the current DPHYSFR against the previous snapshot and emits one event per detected edge:

PWRSF rising -> k_ra8_mipi_phy_event_ldo_ready
PWRSF falling -> k_ra8_mipi_phy_event_ldo_lost
PLLSF rising -> k_ra8_mipi_phy_event_pll_locked
PLLSF falling -> k_ra8_mipi_phy_event_pll_lost

If neither bit moved, a single k_ra8_mipi_phy_event_status_chg is emitted so the consumer at least knows the PHY was polled.

Precondition: – (no preconditions; tolerates the callback being NULL).; Called from ISR context, host-test driver or polling task.

Postcondition: DPHYSFR has been read once; no register has been written.; Internal status snapshot is updated for the next edge compare.

Note: Thread safety: not thread-safe. See HUM Ch 64.2 p 3835.

Since: 0.1.0

Definition at line 560 of file ra8_mipi_phy.c.

References k_ra8_mipi_phy_event_ldo_lost, k_ra8_mipi_phy_event_ldo_ready, k_ra8_mipi_phy_event_pll_locked, k_ra8_mipi_phy_event_pll_lost, k_ra8_mipi_phy_event_status_chg, k_ra8_mipi_phy_off_sfr, k_ra8_mipi_phy_sfr_pllsf, k_ra8_mipi_phy_sfr_pwrsf, ra8_mipi_phy_reg32(), s_last_sfr, s_mipi_phy_ctx, and s_mipi_phy_fn.

◆ ra8_mipi_phy_enter_stop()

ra8_err_t ra8_mipi_phy_enter_stop ( void )

nodiscard

Pre-standby tear-down: disable D-PHY then drop the LDO.

HUM Ch 64.4.1 p 3837: "Before transitioning to graphics power domain off or Software Standby mode, stop the operation as described in section 64.3.2." This is a thin wrapper that calls ra8_mipi_phy_deinit.

Returns: ra8_err_t error code (see ra8_mipi_phy_deinit).

Precondition: Caller is about to enter graphics-domain-off or standby.

Postcondition: LDO is off; the PHY draws no current.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 595 of file ra8_mipi_phy.c.

References ra8_mipi_phy_deinit().

◆ ra8_mipi_phy_exit_stop()

ra8_err_t ra8_mipi_phy_exit_stop ( const ra8_mipi_phy_config_t * cfg )

nodiscard

Post-standby resume: re-run the start-up procedure.

Parameters

[in] cfg Same configuration that was passed to the original ra8_mipi_phy_init.

Returns: ra8_err_t error code (see ra8_mipi_phy_init).

Precondition: Graphics power domain has been re-enabled and PCLKA is running again (HUM 64.3.1 step 1, p 3837).

Postcondition: D-PHY is enabled and the PLL is locked.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 601 of file ra8_mipi_phy.c.

References ra8_mipi_phy_init().

◆ ra8_mipi_phy_get_clock_mode()

ra8_mipi_phy_clk_mode_t ra8_mipi_phy_get_clock_mode ( void )

Query the HS clock-lane mode last configured.

Returns the cached clock-lane mode set by ra8_mipi_phy_set_clock_mode. Per HUM Ch 64.3 p 3837, the PHY does not store the choice itself – the DSI host gates HS-CLK based on this software shadow.

Returns: Active clock mode (defaults to non-continuous).

Return values

k_ra8_mipi_phy_clk_mode_continuous	HS clock free-runs.
k_ra8_mipi_phy_clk_mode_non_continuous	HS clock gated when idle.

Precondition: – (no preconditions; safe before init).; ra8_mipi_phy_set_clock_mode may or may not have been called.

Postcondition: Hardware state is unchanged.; Cached clock-mode value is unchanged.

Note: Thread safety: read-only.

Since: 0.1.0

Definition at line 758 of file ra8_mipi_phy.c.

References s_clk_mode.

◆ ra8_mipi_phy_get_eotp()

ra8_mipi_phy_eotp_t ra8_mipi_phy_get_eotp ( void )

Query the EoTP setting last configured.

Returns the cached End-of-Transmission-Packet preference last set via ra8_mipi_phy_set_eotp. The DSI host honours this when emitting the optional EoTP at the end of HS bursts.

Returns: Active EoTP setting (defaults to disabled).

Return values

k_ra8_mipi_phy_eotp_disabled	EoTP suppression – legacy peripherals.
k_ra8_mipi_phy_eotp_enabled	EoTP appended – spec-compliant.

Precondition: – (no preconditions; safe before init).; ra8_mipi_phy_set_eotp may or may not have been called.

Postcondition: Hardware state is unchanged.; Cached EoTP value is unchanged.

Note: Thread safety: read-only.

Since: 0.1.0

Definition at line 772 of file ra8_mipi_phy.c.

References s_eotp.

◆ ra8_mipi_phy_get_lane_count()

ra8_mipi_phy_lane_count_t ra8_mipi_phy_get_lane_count ( void )

Read back the lane count last configured.

Returns the cached lane-count value last written via ra8_mipi_phy_set_lane_count. The PHY itself has no lane-count register (HUM Ch 64.1 Table 64.1 p 3822); this is a software shadow consulted by ra8_mipi_phy_set_lane_enable.

Returns: Active lane count (defaults to k_ra8_mipi_phy_lane_count_2).

Return values

k_ra8_mipi_phy_lane_count_1	Single-lane mode.
k_ra8_mipi_phy_lane_count_2	Dual-lane (default).

Precondition: – (no preconditions; safe before init).; ra8_mipi_phy_set_lane_count may or may not have been called.

Postcondition: Hardware state is unchanged.; Cached lane-count value is unchanged.

Note: Thread safety: read-only.

Since: 0.1.0

Definition at line 693 of file ra8_mipi_phy.c.

References s_lane_count.

◆ ra8_mipi_phy_get_status()

ra8_err_t ra8_mipi_phy_get_status ( uint32_t * out_mask )

nodiscard

Read the D-PHY status flags (DPHYSFR).

Parameters

[out] out_mask Receives a copy of DPHYSFR (PWRSF | PLLSF).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	*out_mask updated.
k_ra8_err_null_ptr	out_mask was NULL.

Precondition: out_mask is non-NULL.

Postcondition: *out_mask reflects the live register state.

Note: Thread safety: read-only access, safe under simple races.

Since: 0.1.0

Definition at line 524 of file ra8_mipi_phy.c.

References k_ra8_mipi_phy_off_sfr, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_mipi_phy_reg32(), and s_tag.

◆ ra8_mipi_phy_init()

ra8_err_t ra8_mipi_phy_init ( const ra8_mipi_phy_config_t * cfg )

nodiscard

Bring up the D-PHY end-to-end per HUM Ch 64.3.1 p 3837.

Executes the eleven-step start-up procedure:

Ungate the MIPI PHY module (MSTPCRC bit cleared via direct register write – see file header note about MSTP enum).
Write DPHYMDC.MASTEREN to select host vs device.
Write DPHYREFCR.RFREQ from cfg->pclka_mhz.
Set DPHYPWRCR.PWRSEN = 1 to power the LDO.
Spin until DPHYSFR.PWRSF reads 1 or the spin budget runs out (HUM 64.3.1 step 5).
(Host only) write DPHYPLFCR from cfg->pll.
(Host only) write DPHYESCCR.ESCDIV.
(Host only) clear DPHYPLOCR.PLLSTP to release the PLL.
(Host only) spin until DPHYSFR.PLLSF reads 1.
Write DPHYTIM1..6 from cfg->p_timing.
Set DPHYOCR.DPHYEN = 1.

Parameters

[in] cfg Non-NULL configuration block.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	D-PHY enabled, LDO + PLL stable.
k_ra8_err_null_ptr	cfg or cfg->p_timing was NULL.
k_ra8_err_invalid_arg	pclka_mhz outside 40..125 (HUM 64.2.1 p 3822) or PLL fields out of range.
k_ra8_err_not_supported	lane_count > 2.
k_ra8_err_hw_timeout	LDO or PLL did not stabilise in time.

Precondition: Graphics power domain is on and PCLKA is supplied to the MIPI subsystem (HUM Ch 64.3.1 step 1, p 3837).; IRQs masked or single-threaded init context (the driver sequences several register writes that must not be torn).

Postcondition: DPHYOCR.DPHYEN reads 1.; For host mode, DPHYSFR.PLLSF reads 1.

State Machine: <p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p>

Note: Thread safety: not thread-safe.

See also: ra8_mipi_phy_deinit; HUM Ch 64.3.1 p 3837 "D-PHY Startup Procedure"

Since: 0.1.0

Definition at line 432 of file ra8_mipi_phy.c.

References internal_mipi_phy_cache_state(), internal_mipi_phy_init_host(), internal_mipi_phy_init_power_up(), internal_mipi_phy_validate_init_cfg(), k_ra8_mipi_phy_mode_dsi_host, k_ra8_mipi_phy_ocr_dphyen, k_ra8_mipi_phy_off_esccr, k_ra8_mipi_phy_off_ocr, k_ra8_mipi_phy_off_plfcr, k_ra8_mipi_phy_off_plocr, k_ra8_ok, ra8_mipi_phy_config_t::mode, ra8_mipi_phy_config_t::p_timing, priv_mipi_phy_write_timing(), ra8_log_info, ra8_mipi_phy_reg32(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by ra8_board_mipi_dsi_init(), ra8_mipi_phy_exit_stop(), and ra8_mipi_phy_recover_from_error().

◆ ra8_mipi_phy_is_lane_enabled()

bool ra8_mipi_phy_is_lane_enabled ( ra8_mipi_phy_lane_id_t lane )

Query whether the given lane is currently enabled.

Returns the cached enable bit for lane set by ra8_mipi_phy_set_lane_enable. The DSI / CSI host driver consults this when programming its own lane gate.

Parameters

[in] lane Lane identifier (clk, d0, d1).

Returns: true if enabled (default for clk + d0 + d1), else false.

Return values

true	Lane is software-enabled.
false	Lane is software-disabled or out of range.

Precondition: – (no preconditions; safe before init).; lane is a valid ra8_mipi_phy_lane_id_t value.

Postcondition: Hardware state is unchanged.; Cached lane state is unchanged.

Note: Thread safety: read-only.

Since: 0.1.0

Definition at line 730 of file ra8_mipi_phy.c.

References k_ra8_mipi_phy_lane_bit_clk, k_ra8_mipi_phy_lane_bit_d0, k_ra8_mipi_phy_lane_bit_d1, k_ra8_mipi_phy_lane_clk, k_ra8_mipi_phy_lane_d0, k_ra8_mipi_phy_lane_d1, and s_lane_enable_mask.

◆ ra8_mipi_phy_is_ldo_stable()

bool ra8_mipi_phy_is_ldo_stable ( void )

Test whether the LDO has stabilised (DPHYSFR.PWRSF = 1).

Reads the DPHYSFR status register (HUM Ch 64.2 "D-PHY Status", p 3835) and returns the PWRSF bit so callers can poll without unpacking the register layout.

Returns: true if PWRSF is set, false otherwise.

Return values

true	PWRSF asserted – LDO output is in regulation.
false	PWRSF de-asserted – LDO still settling or off.

Precondition: – (no preconditions; safe before init).; LDO power supply present at MCU pin VL_DPHY.

Postcondition: Hardware state is unchanged.; No DPHYSFR write was issued.

Note: Thread safety: read-only.

Since: 0.1.0

Definition at line 533 of file ra8_mipi_phy.c.

References k_ra8_mipi_phy_off_sfr, k_ra8_mipi_phy_sfr_pwrsf, and ra8_mipi_phy_reg32().

◆ ra8_mipi_phy_is_pll_locked()

bool ra8_mipi_phy_is_pll_locked ( void )

Test whether the PLL is locked (DPHYSFR.PLLSF = 1).

Reads DPHYSFR (HUM Ch 64.2 "D-PHY Status", p 3835) and returns the PLLSF bit so callers can poll without unpacking the register layout.

Returns: true if PLLSF is set, false otherwise.

Return values

true	PLLSF asserted – D-PHY PLL is locked.
false	PLLSF de-asserted – PLL not yet locked or unlocked.

Precondition: – (no preconditions; safe before init).; PLL has been programmed via ra8_mipi_phy_init.

Postcondition: Hardware state is unchanged.; No DPHYSFR write was issued.

Note: Thread safety: read-only.

Since: 0.1.0

Definition at line 539 of file ra8_mipi_phy.c.

References k_ra8_mipi_phy_off_sfr, k_ra8_mipi_phy_sfr_pllsf, and ra8_mipi_phy_reg32().

◆ ra8_mipi_phy_ldo_disable()

ra8_err_t ra8_mipi_phy_ldo_disable ( void )

nodiscard

Disable the D-PHY LDO (DPHYPWRCR.PWRSEN = 0) only.

Returns: k_ra8_ok always.

Precondition: – (no preconditions; idempotent).

Postcondition: DPHYPWRCR.PWRSEN reads 0.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 616 of file ra8_mipi_phy.c.

References k_ra8_mipi_phy_off_pwrcr, k_ra8_ok, and ra8_mipi_phy_reg32().

◆ ra8_mipi_phy_ldo_enable()

ra8_err_t ra8_mipi_phy_ldo_enable ( void )

nodiscard

Enable the D-PHY LDO (DPHYPWRCR.PWRSEN = 1) only.

Returns: k_ra8_ok after PWRSF stabilises, k_ra8_err_hw_timeout if the LDO never asserts ready.

Precondition: Module-stop is already cleared.

Postcondition: DPHYPWRCR.PWRSEN reads 1.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 607 of file ra8_mipi_phy.c.

References internal_mipi_phy_wait_set(), k_ra8_mipi_phy_off_pwrcr, k_ra8_mipi_phy_off_sfr, k_ra8_mipi_phy_pwrcr_pwrsen, k_ra8_mipi_phy_sfr_pwrsf, and ra8_mipi_phy_reg32().

◆ ra8_mipi_phy_pll_start()

ra8_err_t ra8_mipi_phy_pll_start ( void )

nodiscard

Release the PLL (DPHYPLOCR.PLLSTP = 0) and wait for lock.

Returns: k_ra8_ok after PLLSF asserts, k_ra8_err_hw_timeout else.

Precondition: LDO has been brought up (PWRSF = 1).; DPHYPLFCR has been programmed.

Postcondition: DPHYSFR.PLLSF reads 1.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 623 of file ra8_mipi_phy.c.

References internal_mipi_phy_wait_set(), k_ra8_mipi_phy_off_plocr, k_ra8_mipi_phy_off_sfr, k_ra8_mipi_phy_sfr_pllsf, and ra8_mipi_phy_reg32().

◆ ra8_mipi_phy_pll_stop()

ra8_err_t ra8_mipi_phy_pll_stop ( void )

nodiscard

Stop the PLL (DPHYPLOCR.PLLSTP = 1).

Returns: k_ra8_ok always.

Precondition: – (no preconditions; idempotent).

Postcondition: DPHYPLOCR.PLLSTP reads 1.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 632 of file ra8_mipi_phy.c.

References k_ra8_mipi_phy_off_plocr, k_ra8_mipi_phy_plocr_pllstp, k_ra8_ok, and ra8_mipi_phy_reg32().

◆ ra8_mipi_phy_recover_from_error()

ra8_err_t ra8_mipi_phy_recover_from_error ( const ra8_mipi_phy_config_t * cfg )

nodiscard

Reset and re-arm the PHY after an LDO drop / PLL unlock.

Parameters

[in] cfg Same configuration that was passed to the original ra8_mipi_phy_init.

Returns: ra8_err_t error code (see ra8_mipi_phy_init).

Precondition: cfg non-NULL.; The PHY was previously initialized at least once.

Postcondition: On success, DPHYEN reads 1 and PLL is locked.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 514 of file ra8_mipi_phy.c.

References RA8_CHECK_NULL_PTR, ra8_mipi_phy_init(), ra8_mipi_phy_reset(), RA8_RETURN_ON_ERROR, and s_tag.

◆ ra8_mipi_phy_reset()

ra8_err_t ra8_mipi_phy_reset ( void )

nodiscard

Reset the PHY to its post-MSTPCRC-clear state without re-init.

Clears DPHYOCR / DPHYPLOCR / DPHYPWRCR and zeros every timing register (DPHYTIM1..6) and DPHYPLFCR. Useful when the higher-level stack hits an unrecoverable error and wants to start over without paying for a full module-stop cycle.

Returns: ra8_err_t error code.

Return values

k_ra8_ok always.

Precondition: – (no preconditions).

Postcondition: DPHYOCR / DPHYPWRCR / DPHYPLOCR / DPHYTIMx / DPHYPLFCR all read their reset values.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 482 of file ra8_mipi_phy.c.

References k_ra8_mipi_phy_off_esccr, k_ra8_mipi_phy_off_mdc, k_ra8_mipi_phy_off_ocr, k_ra8_mipi_phy_off_plfcr, k_ra8_mipi_phy_off_plocr, k_ra8_mipi_phy_off_pwrcr, k_ra8_mipi_phy_off_refcr, k_ra8_mipi_phy_off_tim1, k_ra8_mipi_phy_off_tim2, k_ra8_mipi_phy_off_tim3, k_ra8_mipi_phy_off_tim4, k_ra8_mipi_phy_off_tim5, k_ra8_mipi_phy_off_tim6, k_ra8_mipi_phy_plocr_pllstp, k_ra8_ok, ra8_mipi_phy_reg32(), and s_last_sfr.

Referenced by ra8_mipi_phy_recover_from_error().

◆ ra8_mipi_phy_set_clock_mode()

ra8_err_t ra8_mipi_phy_set_clock_mode ( ra8_mipi_phy_clk_mode_t mode )

nodiscard

Set the HS clock-lane mode (continuous vs non-continuous).

Parameters

[in] mode Clock-lane mode.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Stored.
k_ra8_err_invalid_arg	mode outside the enum.

Precondition: – (no preconditions).

Postcondition: ra8_mipi_phy_get_clock_mode returns mode on success.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 749 of file ra8_mipi_phy.c.

References k_ra8_err_invalid_arg, k_ra8_mipi_phy_clk_continuous, k_ra8_mipi_phy_clk_noncontinuous, k_ra8_ok, and s_clk_mode.

◆ ra8_mipi_phy_set_eotp()

ra8_err_t ra8_mipi_phy_set_eotp ( ra8_mipi_phy_eotp_t eotp )

nodiscard

Set the EoTP packet emission preference (DSI host only).

Parameters

[in] eotp Desired EoTP setting.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Stored.
k_ra8_err_invalid_arg	eotp outside the enum.

Precondition: – (no preconditions).

Postcondition: ra8_mipi_phy_get_eotp returns eotp on success.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 763 of file ra8_mipi_phy.c.

References k_ra8_err_invalid_arg, k_ra8_mipi_phy_eotp_disabled, k_ra8_mipi_phy_eotp_enabled, k_ra8_ok, and s_eotp.

◆ ra8_mipi_phy_set_escape_divisor()

ra8_err_t ra8_mipi_phy_set_escape_divisor ( uint8_t escdiv )

nodiscard

Update DPHYESCCR.ESCDIV at runtime.

HUM Ch 64.2.4 p 3825: ESCDIV[4:0] must be written while DPHYPLOCR.PLLSTP = 1. This helper enforces that by stopping the PLL, writing the divisor, and restarting the PLL.

Parameters

[in] escdiv New escape divisor (0..31).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Divisor updated and PLL re-locked.
k_ra8_err_invalid_arg	escdiv > 31.
k_ra8_err_hw_timeout	PLL did not re-lock within budget.

Precondition: ra8_mipi_phy_init ran successfully (host mode).

Postcondition: DPHYESCCR.ESCDIV equals escdiv on success.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 791 of file ra8_mipi_phy.c.

References internal_mipi_phy_wait_set(), k_ra8_err_invalid_arg, k_ra8_mipi_phy_esccr_escdiv_mask, k_ra8_mipi_phy_escdiv_max, k_ra8_mipi_phy_off_esccr, k_ra8_mipi_phy_off_plocr, k_ra8_mipi_phy_off_sfr, k_ra8_mipi_phy_plocr_pllstp, k_ra8_mipi_phy_sfr_pllsf, and ra8_mipi_phy_reg32().

◆ ra8_mipi_phy_set_lane_count()

ra8_err_t ra8_mipi_phy_set_lane_count ( ra8_mipi_phy_lane_count_t count )

nodiscard

Configure the active lane count.

The PHY has no lane-count register of its own (the DSI / CSI host drivers gate individual lanes), so this helper only validates the argument against the silicon limit and stores it for later inspection through ra8_mipi_phy_get_lane_count. The value is also used by ra8_mipi_phy_set_lane_enable to bound checks.

Parameters

[in] count Desired lane count.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Stored.
k_ra8_err_invalid_arg	count outside 1..4 enum.
k_ra8_err_not_supported	count is 3 or 4 (silicon max 2, HUM Ch 64.1 Table 64.1 p 3822).

Precondition: – (no preconditions).

Postcondition: ra8_mipi_phy_get_lane_count returns count on success.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 673 of file ra8_mipi_phy.c.

References k_ra8_err_invalid_arg, k_ra8_err_not_supported, k_ra8_mipi_phy_lane_bit_d1, k_ra8_mipi_phy_lane_count_1, k_ra8_mipi_phy_lane_count_2, k_ra8_mipi_phy_lane_count_3, k_ra8_mipi_phy_lane_count_4, k_ra8_ok, s_lane_count, and s_lane_enable_mask.

◆ ra8_mipi_phy_set_lane_enable()

ra8_err_t ra8_mipi_phy_set_lane_enable	(	ra8_mipi_phy_lane_id_t	lane,
		bool	enable )

nodiscard

Enable or disable a single data lane.

Mirrors the per-lane gate that the DSI / CSI host drivers expose. The PHY itself has no per-lane register, so this helper only validates the index and stashes the request – the higher-level driver consults ra8_mipi_phy_is_lane_enabled when configuring its own lane gate.

Parameters

[in]	lane	Lane identifier.
[in]	enable	true to enable, false to disable.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Stored.
k_ra8_err_invalid_arg	lane outside the enum or beyond the configured lane_count.
k_ra8_err_not_supported	Lane >= 2 (silicon max).

Precondition: – (no preconditions).

Postcondition: ra8_mipi_phy_is_lane_enabled returns enable on success.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 698 of file ra8_mipi_phy.c.

References k_ra8_err_invalid_arg, k_ra8_err_not_supported, k_ra8_mipi_phy_lane_bit_clk, k_ra8_mipi_phy_lane_bit_d0, k_ra8_mipi_phy_lane_bit_d1, k_ra8_mipi_phy_lane_clk, k_ra8_mipi_phy_lane_count_1, k_ra8_mipi_phy_lane_d0, k_ra8_mipi_phy_lane_d1, k_ra8_mipi_phy_lane_d2, k_ra8_mipi_phy_lane_d3, k_ra8_ok, s_lane_count, and s_lane_enable_mask.

◆ ra8_mipi_phy_set_lane_speed()

ra8_err_t ra8_mipi_phy_set_lane_speed ( const ra8_mipi_phy_pll_t * pll )

nodiscard

Reprogram the PLL coefficients (DPHYPLFCR) at runtime.

HUM Ch 64.2.2 p 3824: DPHYPLFCR may only be written while DPHYPLOCR.PLLSTP = 1. This helper sets PLLSTP, writes DPHYPLFCR from pll, clears PLLSTP, and spins until DPHYSFR.PLLSF re-asserts. The D-PHY enable bit (DPHYOCR.DPHYEN) is left as it was on entry; callers transmitting active video should disable the lane outputs first.

Parameters

[in] pll Non-NULL PLL coefficient block.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	PLL re-locked.
k_ra8_err_null_ptr	pll was NULL.
k_ra8_err_invalid_arg	pll->nmul_int outside 40..375 (HUM 64.2.2 p 3823) or band mismatch.
k_ra8_err_hw_timeout	PLL did not relock within the spin budget.

Precondition: pll is non-NULL.; ra8_mipi_phy_init has already run successfully.

Postcondition: On success, the PLL output frequency reflects the new coefficients and DPHYSFR.PLLSF reads 1.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 639 of file ra8_mipi_phy.c.

References internal_mipi_phy_pack_plfcr(), internal_mipi_phy_validate_pll(), internal_mipi_phy_wait_set(), k_ra8_mipi_phy_off_plfcr, k_ra8_mipi_phy_off_plocr, k_ra8_mipi_phy_off_sfr, k_ra8_mipi_phy_plocr_pllstp, k_ra8_mipi_phy_sfr_pllsf, RA8_CHECK_NULL_PTR, ra8_mipi_phy_reg32(), RA8_RETURN_ON_ERROR, and s_tag.

◆ ra8_mipi_phy_set_pclka_freq()

ra8_err_t ra8_mipi_phy_set_pclka_freq ( uint8_t mhz )

nodiscard

Update DPHYREFCR.RFREQ at runtime.

Parameters

[in] mhz New PCLKA frequency, MHz (40..125).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	RFREQ updated.
k_ra8_err_invalid_arg	mhz outside 40..125 (HUM Ch 64.2.1 p 3822).

Precondition: Module-stop is cleared.

Postcondition: DPHYREFCR.RFREQ equals mhz on success.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 777 of file ra8_mipi_phy.c.

References k_ra8_err_invalid_arg, k_ra8_mipi_phy_off_refcr, k_ra8_mipi_phy_pclka_max_mhz, k_ra8_mipi_phy_pclka_min_mhz, k_ra8_mipi_phy_refcr_rfreq_bias, k_ra8_mipi_phy_refcr_rfreq_mask, k_ra8_ok, and ra8_mipi_phy_reg32().

◆ ra8_mipi_phy_switch_mode()

ra8_err_t ra8_mipi_phy_switch_mode ( ra8_mipi_phy_mode_t mode )

nodiscard

Switch the PHY between DSI host and CSI device mode.

HUM Ch 64.2.14 p 3836: DPHYMDC.MASTEREN selects host vs device. Switching modes requires the D-PHY to be disabled first; this helper clears DPHYEN, rewrites DPHYMDC, and lets the caller re-enable the D-PHY (typically via ra8_mipi_phy_pll_start for host or directly setting DPHYEN for device).

Parameters

[in] mode Target mode.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Mode switched.
k_ra8_err_invalid_arg	mode outside the enum.

Precondition: – (DPHYEN may be 0 or 1 – the helper clears it as needed).

Postcondition: DPHYMDC.MASTEREN reflects mode.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 660 of file ra8_mipi_phy.c.

References k_ra8_err_invalid_arg, k_ra8_mipi_phy_mdc_hosten, k_ra8_mipi_phy_mode_csi_device, k_ra8_mipi_phy_mode_dsi_host, k_ra8_mipi_phy_off_mdc, k_ra8_mipi_phy_off_ocr, k_ra8_ok, and ra8_mipi_phy_reg32().

◆ ra8_mipi_phy_validate_pll_band()

ra8_err_t ra8_mipi_phy_validate_pll_band	(	const ra8_mipi_phy_pll_t *	pll,
		uint8_t	mosc_mhz )

nodiscard

Validate a PLL coefficient block against HUM 64.2.2 p 3823-3824.

Checks the integer N range (40..375), then verifies the resulting PLL output frequency lies within the band selected by PMUL[1:0] (P=1: 960..1440, P=1/2: 480..1440, P=1/4: 240..750, P=1/8: 120..375). The MOSC frequency is taken from the parameter mosc_mhz so the check works without consulting the live CGC state.

Parameters

[in]	pll	Non-NULL PLL coefficient block.
[in]	mosc_mhz	MOSC frequency, MHz (8..48).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Coefficients are within spec.
k_ra8_err_null_ptr	pll was NULL.
k_ra8_err_invalid_arg	Out-of-spec coefficient.

Precondition: pll is non-NULL.; mosc_mhz is between 8 and 48.

Postcondition: Hardware state is unchanged.

Note: Pure function – safe to call from any context.

Since: 0.1.0

Definition at line 808 of file ra8_mipi_phy.c.

◆ ra8_mipi_phy_wait_ready()

ra8_err_t ra8_mipi_phy_wait_ready ( void )

nodiscard

Bounded poll until the PHY is fully ready (PWRSF & PLLSF).

Returns: k_ra8_ok if ready, k_ra8_err_hw_timeout if not.

Precondition: – (no preconditions).

Postcondition: DPHYSFR has been read at least once.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 545 of file ra8_mipi_phy.c.

References internal_mipi_phy_wait_set(), k_ra8_mipi_phy_off_sfr, k_ra8_mipi_phy_sfr_ready_mask, and ra8_mipi_phy_reg32().

Variable Documentation

◆ s_clk_mode

ra8_mipi_phy_clk_mode_t s_clk_mode = k_ra8_mipi_phy_clk_noncontinuous

static

HS clock-lane operating mode (continuous vs non-continuous).

Definition at line 155 of file ra8_mipi_phy.c.

Referenced by internal_mipi_phy_cache_state(), ra8_mipi_phy_get_clock_mode(), and ra8_mipi_phy_set_clock_mode().

◆ s_eotp

ra8_mipi_phy_eotp_t s_eotp = k_ra8_mipi_phy_eotp_disabled

static

Whether DSI host should append EoTP packets (host mode).

Definition at line 161 of file ra8_mipi_phy.c.

Referenced by internal_mipi_phy_cache_state(), ra8_mipi_phy_get_eotp(), and ra8_mipi_phy_set_eotp().

◆ s_lane_count

ra8_mipi_phy_lane_count_t s_lane_count = k_ra8_mipi_phy_lane_count_2

static

Last lane-count argument accepted by ra8_mipi_phy_set_lane_count.

Definition at line 143 of file ra8_mipi_phy.c.

Referenced by internal_mipi_phy_cache_state(), ra8_mipi_phy_get_lane_count(), ra8_mipi_phy_set_lane_count(), and ra8_mipi_phy_set_lane_enable().

◆ s_lane_enable_mask

uint8_t s_lane_enable_mask = k_ra8_mipi_phy_lane_mask_default

static

Bitmap of enabled lanes (bit 0 = clock, bit N = data lane N-1).

Definition at line 149 of file ra8_mipi_phy.c.

Referenced by internal_mipi_phy_cache_state(), ra8_mipi_phy_is_lane_enabled(), ra8_mipi_phy_set_lane_count(), and ra8_mipi_phy_set_lane_enable().

◆ s_last_sfr

uint32_t s_last_sfr

static

Previous DPHYSFR snapshot, used for edge detection in dispatch.

Definition at line 137 of file ra8_mipi_phy.c.

Referenced by internal_mipi_phy_cache_state(), ra8_mipi_phy_dispatch(), and ra8_mipi_phy_reset().

◆ s_mipi_phy_ctx

void* s_mipi_phy_ctx

static

Opaque context forwarded to s_mipi_phy_fn.

Definition at line 131 of file ra8_mipi_phy.c.

Referenced by ra8_mipi_phy_attach_handler(), and ra8_mipi_phy_dispatch().

◆ s_mipi_phy_fn

ra8_mipi_phy_event_fn_t s_mipi_phy_fn

static

Registered callback for ra8_mipi_phy_dispatch.

Definition at line 125 of file ra8_mipi_phy.c.

Referenced by ra8_mipi_phy_attach_handler(), and ra8_mipi_phy_dispatch().

◆ s_tag

const char* s_tag = "MIPI_PHY"

static

Log tag for ra8_log_* calls in this driver.

Definition at line 57 of file ra8_mipi_phy.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_mipi_phy_lane_bit_t

◆ ra8_mipi_phy_lane_mask_t

◆ ra8_mipi_phy_limits_t

◆ ra8_mipi_phy_mstpc_bit_t

Function Documentation

◆ internal_mipi_phy_cache_state()

◆ internal_mipi_phy_init_host()

◆ internal_mipi_phy_init_power_up()

◆ internal_mipi_phy_mstp_unstop()

◆ internal_mipi_phy_pack_plfcr()

◆ internal_mipi_phy_validate_init_cfg()

◆ internal_mipi_phy_validate_pll()

◆ internal_mipi_phy_wait_set()

◆ priv_mipi_phy_write_timing()

◆ ra8_mipi_phy_attach_handler()

◆ ra8_mipi_phy_deinit()

◆ ra8_mipi_phy_dispatch()

◆ ra8_mipi_phy_enter_stop()

◆ ra8_mipi_phy_exit_stop()

◆ ra8_mipi_phy_get_clock_mode()

◆ ra8_mipi_phy_get_eotp()

◆ ra8_mipi_phy_get_lane_count()

◆ ra8_mipi_phy_get_status()

◆ ra8_mipi_phy_init()

◆ ra8_mipi_phy_is_lane_enabled()

◆ ra8_mipi_phy_is_ldo_stable()

◆ ra8_mipi_phy_is_pll_locked()

◆ ra8_mipi_phy_ldo_disable()

◆ ra8_mipi_phy_ldo_enable()

◆ ra8_mipi_phy_pll_start()

◆ ra8_mipi_phy_pll_stop()

◆ ra8_mipi_phy_recover_from_error()

◆ ra8_mipi_phy_reset()

◆ ra8_mipi_phy_set_clock_mode()

◆ ra8_mipi_phy_set_eotp()

◆ ra8_mipi_phy_set_escape_divisor()

◆ ra8_mipi_phy_set_lane_count()

◆ ra8_mipi_phy_set_lane_enable()

◆ ra8_mipi_phy_set_lane_speed()

◆ ra8_mipi_phy_set_pclka_freq()

◆ ra8_mipi_phy_switch_mode()

◆ ra8_mipi_phy_validate_pll_band()

◆ ra8_mipi_phy_wait_ready()

Variable Documentation

◆ s_clk_mode

◆ s_eotp

◆ s_lane_count

◆ s_lane_enable_mask

◆ s_last_sfr

◆ s_mipi_phy_ctx

◆ s_mipi_phy_fn

◆ s_tag