Internal Voltage Regulator (DCDC / LDO) driver – full HUM Ch 68 surface. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_vreg_regs.h"

Include dependency graph for ra8_vreg.h:

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

Data Structures
struct	ra8_vreg_cfg_t
	Configuration descriptor for ra8_vreg_init. More...
struct	ra8_vreg_status_t
	Snapshot of the regulator state. More...

Typedefs
typedef void(*	ra8_vreg_event_fn_t) (void *ctx, uint8_t status_word)
	Voltage-regulator fault callback.

Enumerations
enum	ra8_vreg_mode_t : uint8_t { k_ra8_vreg_mode_ldo = 0U , k_ra8_vreg_mode_dcdc = 1U }
	Runtime regulator mode selection (DCDCCTL.DCDCON). More...
enum	ra8_vreg_lv_profile_t : uint8_t { k_ra8_vreg_lv_off = 0U , k_ra8_vreg_lv_p0 = 1U , k_ra8_vreg_lv_p1 = 2U }
	Low-voltage operation profile (LVOCR). More...
enum	ra8_vreg_standby_t : uint8_t { k_ra8_vreg_standby_software = 0U , k_ra8_vreg_standby_deep_software1 = 1U , k_ra8_vreg_standby_deep_software2 = 2U , k_ra8_vreg_standby_deep_software3 = 3U , k_ra8_vreg_standby_battery_backup = 4U }
	Software Standby variant the caller intends to enter next. More...
enum	ra8_vreg_ocp_t : uint8_t { k_ra8_vreg_ocp_off = 0U , k_ra8_vreg_ocp_normal = 1U , k_ra8_vreg_ocp_low = 2U , k_ra8_vreg_ocp_high = 3U }
	DCDC over-current protection threshold programming. More...

Functions
ra8_err_t	ra8_vreg_init (const ra8_vreg_cfg_t *cfg)
	Initialise the internal voltage regulator from a config descriptor.
ra8_err_t	ra8_vreg_deinit (void)
	Tear down the regulator – return DCDCCTL/VCCSEL/LVOCR to reset state.
ra8_err_t	ra8_vreg_set_mode (ra8_vreg_mode_t mode)
	Switch between LDO and DCDC at runtime.
ra8_err_t	ra8_vreg_set_vccsel (ra8_vreg_vccsel_t sel)
	Set the DCDC supply-voltage-range select.
ra8_err_t	ra8_vreg_set_ocp (ra8_vreg_ocp_t level)
	Program the DCDC over-current-protection level.
ra8_err_t	ra8_vreg_set_fast_startup (bool enable)
	Enable / disable the DCDC fast-startup sequence.
ra8_err_t	ra8_vreg_set_ldo_boost (bool enable)
	Enable / disable the LDO charge-pump boost.
ra8_err_t	ra8_vreg_set_lv_profile (ra8_vreg_lv_profile_t profile)
	Select a low-voltage operation profile.
ra8_err_t	ra8_vreg_get_status (ra8_vreg_status_t *out)
	Read the regulator status into a caller-supplied snapshot.
ra8_err_t	ra8_vreg_clear_status (uint8_t mask)
	Clear the bits in DCDCCTL named by mask.
ra8_err_t	ra8_vreg_reset (void)
	Reset the regulator to its OFS-byte default state.
ra8_err_t	ra8_vreg_enter_standby (ra8_vreg_standby_t variant)
	Park the regulator for one of the Software Standby variants.
ra8_err_t	ra8_vreg_enter_stop (void)
	Legacy alias for ra8_vreg_enter_standby(k_ra8_vreg_standby_software).
ra8_err_t	ra8_vreg_exit_standby (void)
	Restore the regulator after Software Standby exit.
ra8_err_t	ra8_vreg_exit_stop (void)
	Legacy alias for ra8_vreg_exit_standby().
ra8_err_t	ra8_vreg_attach_handler (ra8_vreg_event_fn_t fn, void *ctx)
	Attach a fault callback (LVD / over-current dispatch hook).
void	ra8_vreg_dispatch (void)
	Fire the registered fault callback with the current DCDCCTL value.

Detailed Description

Internal Voltage Regulator (DCDC / LDO) driver – full HUM Ch 68 surface.

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

The RA8D2 core voltage rail (VDD) is sourced from one of two regulators selected at flash-programming time by the OFS2.DCDCEN option byte (HUM Ch 68.1):

DCDC mode – on-chip switching regulator with external 2.2-uH inductor and 47-uF capacitor on every VLO pin. Highest efficiency in High-Speed and Middle-Speed operating modes; does not support Software Standby, Deep Software Standby modes 1/2/3, Battery Backup or Voltage Scaling Control.
External VDD mode – VDD supplied directly to the VCL pins from an external regulator; the on-chip DCDC is bypassed.

Once the OFS byte selects a topology, the runtime API in this file is responsible for:

Bringing the regulator to a known state (ra8_vreg_init).
Selecting the supply-voltage range so the DCDC biases correctly for the board's actual VCC (ra8_vreg_set_vccsel).
Switching between DCDC and LDO power modes at runtime (ra8_vreg_set_mode) – this is the same transition FSP performs in bsp_clocks.c when entering Subosc-speed mode.
Toggling the LDO charge-pump boost (ra8_vreg_set_ldo_boost) so the LDO can regulate VDD all the way down to the subosc-speed window.
Programming the OCP threshold (ra8_vreg_set_ocp) to match the board's expected current envelope.
Choosing the fast-startup or normal startup sequence (ra8_vreg_set_fast_startup).
Selecting one of the documented Low-Voltage profiles (ra8_vreg_set_lv_profile).
Parking the chip for any of the Software Standby variants (ra8_vreg_enter_standby) and restoring afterwards.
Reading status (ra8_vreg_get_status).
Powering the block down (ra8_vreg_deinit).

What the driver intentionally does NOT do

Reprogram OFS2 – that's a one-shot factory operation handled by the FLASH driver.
Touch LVD trip points – see ra8_lvd for that.
Sequence the full Software Standby exit (clock restart, RAM wake) – see ra8_lpm. This driver only parks / restores the regulator state; the LPM driver wraps the WFI.

State machine

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

From	To	Function	Allowed?
Reset	LDO	ra8_vreg_init	always
Reset	DCDC	ra8_vreg_init	OFS2.DCDCEN=1
LDO	DCDC	ra8_vreg_set_mode	VCC >= 2.4 V
DCDC	LDO	ra8_vreg_set_mode	always
LDO	Standby	ra8_vreg_enter_standby	always
DCDC	Standby	ra8_vreg_enter_standby	rejected
DCDC	DSBY	ra8_vreg_enter_standby	rejected

IRQ surface

The voltage regulator block itself does not raise an interrupt on RA8D2; over-current / under-voltage events are reported through the LVD channels and the DCDC over-current detector inside the LPM IRQ. This driver therefore exposes only attach_handler as a forwarding hook – the caller wires the LVD ISR to call back here if a unified "VREG fault" callback is desired.

Warning

Misconfiguring the regulator can damage the chip or cause undervoltage resets. In particular:

DCDC mode requires VCC >= 2.4 V at all times. Below that threshold the regulator must be switched back to LDO via ra8_vreg_set_mode(k_ra8_vreg_mode_ldo).
Switching to DCDC blocks for ~22 us with all interrupts disabled; switching back to LDO blocks for ~60 us.
VCCSEL must match the actual board VCC range or the DCDC efficiency curve will be wrong and the part may overheat.
Setting both LVO0E and LVO1E in LVOCR is undefined – use ra8_vreg_set_lv_profile() to enforce mutual exclusion.

See also: HUM Ch 68 "Internal Voltage Regulator" p 4032-4034.

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

Definition in file ra8_vreg.h.

Typedef Documentation

◆ ra8_vreg_event_fn_t

typedef void(* ra8_vreg_event_fn_t) (void *ctx, uint8_t status_word)

Voltage-regulator fault callback.

Invoked from ra8_vreg_dispatch(). The driver does not own an IRQ line on RA8D2 – a higher layer (typically the LVD or a user fault router) wires its ISR to call ra8_vreg_dispatch() so this callback can run.

Parameters

[in]	ctx	Caller context recorded at attach time.
[in]	status_word	Snapshot of DCDCCTL at dispatch time.

Definition at line 261 of file ra8_vreg.h.

Enumeration Type Documentation

◆ ra8_vreg_lv_profile_t

enum ra8_vreg_lv_profile_t : uint8_t

Low-voltage operation profile (LVOCR).

The chip exposes two mutually exclusive low-voltage profiles:

Profile 0 (LVO0E=1, LVO1E=0) – relaxed timing for VDD in the 1.6-1.8 V window.
Profile 1 (LVO0E=0, LVO1E=1) – relaxed timing for VDD in the 1.8-2.0 V window.

The "off" value clears LVOCR entirely so the chip runs the full-speed timing.

Enumerator
k_ra8_vreg_lv_off	Both LVO0E and LVO1E cleared (full-speed).
k_ra8_vreg_lv_p0	LVO0E set, LVO1E cleared.
k_ra8_vreg_lv_p1	LVO1E set, LVO0E cleared.

Definition at line 159 of file ra8_vreg.h.

◆ ra8_vreg_mode_t

enum ra8_vreg_mode_t : uint8_t

Runtime regulator mode selection (DCDCCTL.DCDCON).

Enumerator
k_ra8_vreg_mode_ldo	Low-dropout linear regulator (default at reset).
k_ra8_vreg_mode_dcdc	Switching regulator (DCDC).

Definition at line 139 of file ra8_vreg.h.

◆ ra8_vreg_ocp_t

enum ra8_vreg_ocp_t : uint8_t

DCDC over-current protection threshold programming.

The chip only exposes a single OCP enable bit (DCDCCTL.OCPEN); the "level" enums in this file map onto enabling OCP plus tracking the caller's policy in software so a future silicon stepping with a multi-level OCP can grow the API without breaking callers.

off – OCPEN cleared; no over-current protection. Used during the LDO->DCDC handshake before the DCDC stabilises.
normal – OCPEN set; standard threshold (this is the only level the silicon actually programs today).
low – Reserved for a future stepping; today the driver accepts the value but programs the same OCPEN bit.
high – Same as low but reserved for the high-current rail.

Enumerator
k_ra8_vreg_ocp_off	OCPEN cleared.
k_ra8_vreg_ocp_normal	OCPEN set; default threshold.
k_ra8_vreg_ocp_low	OCPEN set; reserved for future use.
k_ra8_vreg_ocp_high	OCPEN set; reserved for future use.

Definition at line 201 of file ra8_vreg.h.

◆ ra8_vreg_standby_t

enum ra8_vreg_standby_t : uint8_t

Software Standby variant the caller intends to enter next.

Used by ra8_vreg_enter_standby() to validate the regulator state. HUM Ch 68.2.2 explicitly forbids DCDC mode for any of these variants – the driver returns k_ra8_err_invalid_state if the current mode is DCDC.

Enumerator
k_ra8_vreg_standby_software	Software Standby mode.
k_ra8_vreg_standby_deep_software1	Deep Software Standby mode 1.
k_ra8_vreg_standby_deep_software2	Deep Software Standby mode 2.
k_ra8_vreg_standby_deep_software3	Deep Software Standby mode 3.
k_ra8_vreg_standby_battery_backup	Battery Backup wake source.

Definition at line 175 of file ra8_vreg.h.

Function Documentation

◆ ra8_vreg_attach_handler()

ra8_err_t ra8_vreg_attach_handler	(	ra8_vreg_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach a fault callback (LVD / over-current dispatch hook).

The callback is invoked synchronously from ra8_vreg_dispatch(). Setting fn = nullptr detaches.

Parameters

[in]	fn	Callback or nullptr to clear.
[in]	ctx	Context forwarded to the callback.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: Single-threaded init or IRQs masked.; ctx may be NULL if the callback does not need it.

Postcondition: Subsequent ra8_vreg_dispatch calls invoke fn(ctx, ...).

Note: Not thread-safe.

Since: 0.1.0

Definition at line 657 of file ra8_vreg.c.

References k_ra8_ok, s_vreg_ctx, and s_vreg_fn.

◆ ra8_vreg_clear_status()

ra8_err_t ra8_vreg_clear_status ( uint8_t mask )

nodiscard

Clear the bits in DCDCCTL named by mask.

Convenience helper for ISR bookkeeping. The caller passes a mask built from k_ra8_vreg_mask_* values; the corresponding bits are cleared in DCDCCTL while the rest are preserved. Any bits outside k_ra8_vreg_mask_dcdcctl_all are rejected with k_ra8_err_invalid_arg.

Parameters

[in] mask Bit mask of DCDCCTL bits to clear.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Success.
k_ra8_err_invalid_arg	mask includes reserved bits.

Precondition: Caller has unlocked PRCR group 1.; mask only contains bits from k_ra8_vreg_mask_dcdcctl_all.

Postcondition: DCDCCTL has the bits in mask cleared.

Since: 0.1.0

Definition at line 577 of file ra8_vreg.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vreg_mask_dcdcctl_all, ra8_vreg_dcdcctl(), and s_state.

◆ ra8_vreg_deinit()

ra8_err_t ra8_vreg_deinit ( void )

nodiscard

Tear down the regulator – return DCDCCTL/VCCSEL/LVOCR to reset state.

Forces the chip back into LDO mode (DCDCCTL = 0) and clears VCCSEL and LVOCR. Safe to call from any state; if the chip was running in DCDC mode it transitions to LDO first.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always (no failure path).

Precondition: Caller has unlocked PRCR group 1.; IRQs masked.

Postcondition: DCDCCTL == 0.; VCCSEL == 0.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 408 of file ra8_vreg.c.

References k_ra8_ok, k_ra8_vreg_lv_off, k_ra8_vreg_ocp_off, k_ra8_vreg_vccsel_2v4_to_2v7, ra8_vreg_dcdcctl(), ra8_vreg_lvocr(), ra8_vreg_vccsel(), and s_state.

Referenced by ra8_vreg_reset().

◆ ra8_vreg_dispatch()

void ra8_vreg_dispatch ( void )

Fire the registered fault callback with the current DCDCCTL value.

Intended to be called from the LVD / fault-router ISR. Snapshots DCDCCTL (HUM Ch 11 "Voltage Regulator (VREG)", p 581) and forwards the value to the registered callback. No-op when no callback is attached.

Precondition: Called from ISR context or a host-test driver.; VREG MSTP gate is open.

Postcondition: Registered callback executed once.; DCDCCTL is unchanged.

Note: Not thread-safe; pair with NVIC masking.

Since: 0.1.0

Definition at line 664 of file ra8_vreg.c.

References ra8_vreg_dcdcctl(), s_vreg_ctx, and s_vreg_fn.

◆ ra8_vreg_enter_standby()

ra8_err_t ra8_vreg_enter_standby ( ra8_vreg_standby_t variant )

nodiscard

Park the regulator for one of the Software Standby variants.

Software Standby, Deep Software Standby modes 1/2/3, Battery Backup and Voltage Scaling Control are all incompatible with DCDC mode (HUM Ch 68.2.2 p 4033). The driver:

Validates variant against the enum.
Caches the current DCDCCTL/VCCSEL/LVOCR for restore.
If the chip is in DCDC mode, switches to LDO and clears OCPEN.

The actual WFI is the caller's responsibility (see ra8_lpm).

Parameters

[in] variant Software Standby variant the caller intends to enter.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Regulator parked.
k_ra8_err_invalid_arg	variant outside the enum.

Precondition: Caller has unlocked PRCR group 1.; Caller drives the chip into Software Standby immediately after.

Postcondition: DCDCCTL.DCDCON == 0 (LDO mode).; DCDCCTL.OCPEN == 0.

Since: 0.1.0

Definition at line 610 of file ra8_vreg.c.

References internal_dcdc_disable_sequence(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vreg_standby_battery_backup, and s_state.

Referenced by ra8_vreg_enter_stop().

◆ ra8_vreg_enter_stop()

ra8_err_t ra8_vreg_enter_stop ( void )

nodiscard

Legacy alias for ra8_vreg_enter_standby(k_ra8_vreg_standby_software).

Kept as a thin wrapper because the lower-level LPM driver still calls the older signature. Internally just forwards.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Since: 0.1.0

Definition at line 625 of file ra8_vreg.c.

References k_ra8_vreg_standby_software, and ra8_vreg_enter_standby().

◆ ra8_vreg_exit_standby()

ra8_err_t ra8_vreg_exit_standby ( void )

nodiscard

Restore the regulator after Software Standby exit.

If the firmware was running in DCDC mode before ra8_vreg_enter_standby, this restores VCCSEL and re-enables DCDC with OCP. Otherwise it leaves the LDO running.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Success.

Precondition: Caller has unlocked PRCR group 1.; ra8_vreg_init previously ran (so the desired state is cached).

Postcondition: DCDCCTL/VCCSEL match the cached state.

Since: 0.1.0

Definition at line 630 of file ra8_vreg.c.

References k_ra8_ok, k_ra8_vreg_vccsel_mask, ra8_vreg_dcdcctl(), ra8_vreg_lvocr(), ra8_vreg_vccsel(), and s_state.

Referenced by ra8_vreg_exit_stop().

◆ ra8_vreg_exit_stop()

ra8_err_t ra8_vreg_exit_stop ( void )

nodiscard

Legacy alias for ra8_vreg_exit_standby().

Returns: ra8_err_t – forwards to ra8_vreg_exit_standby().

Since: 0.1.0

Definition at line 647 of file ra8_vreg.c.

References ra8_vreg_exit_standby().

◆ ra8_vreg_get_status()

ra8_err_t ra8_vreg_get_status ( ra8_vreg_status_t * out )

nodiscard

Read the regulator status into a caller-supplied snapshot.

Parameters

[out] out Non-NULL receiver for the snapshot.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Success.
k_ra8_err_null_ptr	out was NULL.

Precondition: out is a valid writable pointer.; Single-threaded read or with IRQs masked.

Postcondition: out->dcdcctl / out->vccsel / out->lvocr reflect the live register values.; out->mode / out->vccsel_dec / out->dcdc_ready reflect the decoded state.

Since: 0.1.0

Definition at line 544 of file ra8_vreg.c.

◆ ra8_vreg_init()

ra8_err_t ra8_vreg_init ( const ra8_vreg_cfg_t * cfg )

nodiscard

Initialise the internal voltage regulator from a config descriptor.

Programs DCDCCTL / VCCSEL / LVOCR according to cfg. Selecting k_ra8_vreg_mode_dcdc runs the FSP-style four-step DCDC enable sequence (enable IO buffer -> turn on Vref -> low-power Vref -> switch DCDC + LDO off + OCP enable). The transition is purely register writes here; on real silicon the caller must hold the 22 us / 60 us delays prescribed by HUM Ch 68 between steps.

Algorithm:

Validate every field of cfg.
Clear LVOCR so neither low-voltage profile is left over.
Program VCCSEL.
Issue the LDO->DCDC handshake (or write a single LDO value).
Apply LDO charge-pump boost if requested.
Apply the requested LV profile last.
Cache the desired state for ra8_vreg_exit_standby().

Parameters

[in] cfg Non-NULL configuration descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Success.
k_ra8_err_null_ptr	cfg was NULL.
k_ra8_err_invalid_arg	cfg->vccsel, cfg->ocp or cfg->lv_profile was out of range.

Precondition: IRQs masked or single-threaded init context.; Caller has unlocked PRCR group 1 (LPM/VREG protection).

Postcondition: DCDCCTL reflects cfg->mode | cfg->ocp | cfg->fast_startup | cfg->ldo_boost.; VCCSEL reflects cfg->vccsel when cfg->mode == DCDC.; LVOCR reflects cfg->lv_profile.

Note: Not thread-safe.

Warning: Switching modes without the prescribed wait times can latch the DCDC into an undefined state – on real silicon, insert HUM Ch 68 software delays between steps.

See also: ra8_vreg_set_mode; ra8_vreg_set_vccsel

Since: 0.1.0

Definition at line 353 of file ra8_vreg.c.

References ra8_vreg_cfg_t::fast_startup, internal_dcdc_enable_sequence(), internal_lvocr_from_profile(), internal_pack_ldo_dcdcctl(), internal_validate_cfg(), k_ra8_ok, k_ra8_vreg_mode_dcdc, k_ra8_vreg_standby_software, k_ra8_vreg_vccsel_mask, ra8_vreg_cfg_t::ldo_boost, ra8_vreg_cfg_t::lv_profile, ra8_vreg_cfg_t::mode, ra8_vreg_cfg_t::ocp, RA8_CHECK_NULL_PTR, ra8_log_info, ra8_vreg_dcdcctl(), ra8_vreg_lvocr(), ra8_vreg_vccsel(), s_state, s_tag, and ra8_vreg_cfg_t::vccsel.

◆ ra8_vreg_reset()

ra8_err_t ra8_vreg_reset ( void )

nodiscard

Reset the regulator to its OFS-byte default state.

Equivalent to ra8_vreg_deinit() followed by clearing the cached "desired" state – useful for restarting after a recoverable fault (LVD trip, watchdog warning) without having to re-derive the full config.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: Caller has unlocked PRCR group 1.; IRQs masked.

Postcondition: DCDCCTL == 0, VCCSEL == 0, LVOCR == 0.; Cached "desired" state cleared.

Since: 0.1.0

Definition at line 596 of file ra8_vreg.c.

References k_ra8_vreg_standby_software, ra8_vreg_deinit(), and s_state.

◆ ra8_vreg_set_fast_startup()

ra8_err_t ra8_vreg_set_fast_startup ( bool enable )

nodiscard

Enable / disable the DCDC fast-startup sequence.

When fast-startup is enabled, the LDO->DCDC handshake skips the long Vref soak and uses a single 22 us total transition (vs the default ~32 us). Useful when the firmware needs to leave Software Standby quickly and the analog Vref can be guaranteed stable from the previous run.

Parameters

[in] enable True to set DCDCCTL.FST, false to clear.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: Caller has unlocked PRCR group 1.; Caller understands that fast-startup is only valid when the DCDC has previously stabilised.

Postcondition: DCDCCTL.FST matches enable.

Since: 0.1.0

Definition at line 490 of file ra8_vreg.c.

References k_ra8_ok, k_ra8_vreg_mask_fst, ra8_vreg_dcdcctl(), and s_state.

◆ ra8_vreg_set_ldo_boost()

ra8_err_t ra8_vreg_set_ldo_boost ( bool enable )

nodiscard

Enable / disable the LDO charge-pump boost.

The LDO needs the charge-pump boost (DCDCCTL.LCBOOST) when the chip is targeted for Subosc-speed mode – without it the LDO cannot regulate VDD all the way down. FSP enables LCBOOST as part of the "LDO_BOOST" power-mode enum returned by R_BSP_PowerModeSet; this driver exposes it as a standalone toggle so the caller can mix it with arbitrary OPCCR settings.

Parameters

[in] enable True to set LCBOOST, false to clear.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: Caller has unlocked PRCR group 1.; Regulator is in LDO mode (LCBOOST is ignored in DCDC mode).

Postcondition: DCDCCTL.LCBOOST matches enable.

Since: 0.1.0

Definition at line 507 of file ra8_vreg.c.

References k_ra8_ok, k_ra8_vreg_mask_lcboost, ra8_vreg_dcdcctl(), and s_state.

◆ ra8_vreg_set_lv_profile()

ra8_err_t ra8_vreg_set_lv_profile ( ra8_vreg_lv_profile_t profile )

nodiscard

Select a low-voltage operation profile.

Writes LVOCR to enforce mutual exclusion of LVO0E and LVO1E. Callers that just want full-speed timing pass k_ra8_vreg_lv_off.

Parameters

[in] profile One of k_ra8_vreg_lv_off / lv_p0 / lv_p1.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Success.
k_ra8_err_invalid_arg	profile outside the enum.

Precondition: Caller has unlocked PRCR group 1.; Caller has set VDD into the corresponding voltage window.

Postcondition: LVOCR reflects exactly one bit (or zero).

Since: 0.1.0

Definition at line 523 of file ra8_vreg.c.

References internal_lvocr_from_profile(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vreg_lv_p1, ra8_vreg_lvocr(), and s_state.

◆ ra8_vreg_set_mode()

ra8_err_t ra8_vreg_set_mode ( ra8_vreg_mode_t mode )

nodiscard

Switch between LDO and DCDC at runtime.

Performs the LDO->DCDC or DCDC->LDO transition. On real silicon the caller must respect the 22 us / 60 us blocking windows; in driver code the writes are issued immediately and the caller supplies the timer.

Parameters

[in] mode Target regulator mode.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Success.
k_ra8_err_invalid_arg	mode outside the enum.

Precondition: Caller has unlocked PRCR group 1.; VCC supply is in the range previously programmed via ra8_vreg_set_vccsel.

Postcondition: DCDCCTL.DCDCON reflects mode.; On DCDC mode entry, OCPEN is enabled.

Note: Not thread-safe.

Warning: Entering DCDC mode while VCC < 2.4 V will cause an undervoltage reset.

Since: 0.1.0

Definition at line 438 of file ra8_vreg.c.

References internal_dcdc_disable_sequence(), internal_dcdc_enable_sequence(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vreg_mask_lcboost, k_ra8_vreg_mode_dcdc, k_ra8_vreg_mode_ldo, and s_state.

◆ ra8_vreg_set_ocp()

ra8_err_t ra8_vreg_set_ocp ( ra8_vreg_ocp_t level )

nodiscard

Program the DCDC over-current-protection level.

Sets or clears DCDCCTL.OCPEN according to level. The non-off levels program the same hardware bit today (the silicon only has one OCP threshold) but the driver records the requested level so a future stepping can grow the API without breaking callers.

Parameters

[in] level OCP level enum.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Success.
k_ra8_err_invalid_arg	level outside the enum.

Precondition: Caller has unlocked PRCR group 1.; Regulator is in DCDC mode (or the call is staging for a subsequent LDO->DCDC switch).

Postcondition: DCDCCTL.OCPEN matches level != k_ra8_vreg_ocp_off.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 471 of file ra8_vreg.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vreg_mask_ocpen, k_ra8_vreg_ocp_high, k_ra8_vreg_ocp_off, ra8_vreg_dcdcctl(), and s_state.

◆ ra8_vreg_set_vccsel()

ra8_err_t ra8_vreg_set_vccsel ( ra8_vreg_vccsel_t sel )

nodiscard

Set the DCDC supply-voltage-range select.

VCCSEL is only consulted by the chip in DCDC mode – this driver still permits writing it in any mode so the caller can pre-stage the value before switching modes.

Parameters

[in] sel One of k_ra8_vreg_vccsel_*.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Success.
k_ra8_err_invalid_arg	sel is outside the 2-bit field.

Precondition: Caller has unlocked PRCR group 1.; sel is one of the documented enum values.

Postcondition: VCCSEL reflects sel.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 459 of file ra8_vreg.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vreg_vccsel_3v0_to_3v6, k_ra8_vreg_vccsel_mask, ra8_vreg_vccsel(), and s_state.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

What the driver intentionally does NOT do

State machine

IRQ surface

Typedef Documentation

◆ ra8_vreg_event_fn_t

Enumeration Type Documentation

◆ ra8_vreg_lv_profile_t

◆ ra8_vreg_mode_t

◆ ra8_vreg_ocp_t

◆ ra8_vreg_standby_t

Function Documentation

◆ ra8_vreg_attach_handler()

◆ ra8_vreg_clear_status()

◆ ra8_vreg_deinit()

◆ ra8_vreg_dispatch()

◆ ra8_vreg_enter_standby()

◆ ra8_vreg_enter_stop()

◆ ra8_vreg_exit_standby()

◆ ra8_vreg_exit_stop()

◆ ra8_vreg_get_status()

◆ ra8_vreg_init()

◆ ra8_vreg_reset()

◆ ra8_vreg_set_fast_startup()

◆ ra8_vreg_set_ldo_boost()

◆ ra8_vreg_set_lv_profile()

◆ ra8_vreg_set_mode()

◆ ra8_vreg_set_ocp()

◆ ra8_vreg_set_vccsel()