ra8_mipi_phy_api.h File Reference

MIPI D-PHY driver – public function prototypes. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_mipi_phy_regs.h"
#include "ra8_mipi_phy_types.h"

Include dependency graph for ra8_mipi_phy_api.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
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).

Detailed Description

MIPI D-PHY driver – public function prototypes.

Tag

[Ring 3 / HAL] {World: NS}

Public entry points for the RA8D2 MIPI PHY block (HUM Ch 64, p 3822-3838). This sub-header declares the lifecycle, status, interrupt-path, power-transition, and operations prototypes. The enums, structs, and callback typedef these prototypes reference live in ra8_mipi_phy_types.h, which this header includes. Both are re-exported by the thin umbrella ra8_mipi_phy.h.

Module-stop note

HUM Ch 64.4.2 p 3838: MIPI PHY is gated by MSTPCRC. There is no k_ra8_mstp_mipi_phy entry in libs/ra8_hal/inc/ra8_mstp_regs.h yet. This driver does NOT add one (touching a shared enum file is forbidden); ra8_mipi_phy_init performs a direct MSTPCRC write with a TODO marker so a later wave can promote it into ra8_mstp_t.

Copyright

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

Since

0.1.0

Definition in file ra8_mipi_phy_api.h.

Function Documentation

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_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:

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

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_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_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().