ADC16H (16-bit SAR) converter driver implementation. More...

#include <stdint.h>
#include "adc_internal.h"
#include "ra8_adc.h"
#include "ra8_adc_b_regs.h"
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"

Include dependency graph for adc.c:

Data Structures
struct	ra8_adc_group_cache_t
	Per-scan-group channel-list cache. More...
struct	ra8_adc_state_t
	Driver-wide runtime state. More...

Enumerations
enum	ra8_adc_default_group_t : uint8_t { k_ra8_adc_default_group = 0U }
	Scan-group used by the legacy single-channel polling API. More...

Functions
static bool	internal_adprc_for_resolution (ra8_adc_resolution_t resolution, uint32_t *out_adprc)
	Translate a public resolution selector into its ADDOPCRC.ADPRC code.
static void	internal_write_adprc (uint8_t vch, uint32_t adprc)
	Write the ADPRC data-format field of one ADDOPCRCn slot (RMW).
static void	internal_apply_resolution_code (uint32_t adprc)
	Install one ADPRC data-format code on every result-producing channel.
static void	internal_wait_clksr (uint32_t desired)
	Best-effort wait for ADCLKSR.CLKSR to match the requested level.
static void	internal_clock_bring_up (uint32_t clkcr_value)
	Bring ADCLK up: ENR=0 -> wait CLKSR=0 -> CR=src -> ENR=1 -> CLKSR=1.
static void	internal_zero_channel_table (void)
	Default-zero every per-channel ADCHCRn slot.
static void	internal_program_channel (uint8_t virtual_ch, uint8_t physical_ch)
	Programme an ADCHCRn slot to map a physical channel into the default scan group with no special sample-and-hold.
static uint32_t	internal_build_admdr (bool scan_mode)
	Build the ADMDR value (ADMD0 only – ADC1 stays disabled).
ra8_err_t	ra8_adc_init (void)
	Legacy init – 14-bit right-aligned, software trigger.
ra8_err_t	ra8_adc_read_channel (uint8_t channel, uint16_t *out_raw)
	Blocking single-channel sample.
ra8_err_t	ra8_adc_init_configured (const ra8_adc_cfg_t *cfg)
	Initialise ADC_B with a full config descriptor.
ra8_err_t	ra8_adc_deinit (void)
	Tear down the ADC_B peripheral.
ra8_err_t	ra8_adc_set_resolution (ra8_adc_resolution_t resolution)
	Change the ADC conversion resolution at runtime.
ra8_err_t	ra8_adc_get_status (uint16_t *out_mask)
	Read the ADC status bits (ADCSR.ADST / ADIE).
ra8_err_t	ra8_adc_clear_status (void)
	Clear the ADCSR.ADST busy bit (abort in-flight conversion).
ra8_err_t	ra8_adc_attach_handler (ra8_adc_complete_fn_t fn, void *ctx)
	Attach a conversion-complete callback.
ra8_err_t	ra8_adc_enter_stop (void)
	Put ADC_B into MSTP-gated stop.
ra8_err_t	ra8_adc_exit_stop (void)
	Exit MSTP-gated stop.
void	ra8_adc_dispatch_cnv_end (uint8_t channel)
	Dispatch conversion-complete – read result + fire callback.
static ra8_err_t	internal_validate_group_cfg (uint8_t group, const ra8_adc_scan_group_cfg_t *cfg)
	Validate a scan-group configuration descriptor.
static ra8_err_t	internal_oversample_encode (ra8_adc_oversample_t mode, uint32_t out_avemd, uint32_t out_adc)
	Translate the public oversampling enum into ADDOPCRB AVEMD/ADC.
static ra8_err_t	internal_program_group_channels (uint8_t group, const ra8_adc_scan_group_cfg_t *cfg)
	Walk the channel list and program ADCHCR[ch] = (SGSEL, CNVCS).
static void	internal_cache_group_channels (uint8_t group, const ra8_adc_scan_group_cfg_t *cfg)
	Cache a group's channel list into s_adc_state.groups.
static void	internal_apply_group_enable (uint8_t group, ra8_adc_trigger_src_t trigger)
	Apply the per-group enable bit (ADSGER) and trigger source (ADTRGENR).
ra8_err_t	ra8_adc_configure_scan_group (uint8_t group, const ra8_adc_scan_group_cfg_t *cfg)
	Configure scan group `group` with a list of channels + trigger.
ra8_err_t	ra8_adc_start_group (uint8_t group)
	Kick a scan group via the per-group ADSTR register.
ra8_err_t	ra8_adc_stop_group (uint8_t group)
	Stop a scan group: clear ADSTR[group] and write ADSTOPR.
ra8_err_t	ra8_adc_read_group_results (uint8_t group, uint16_t out_buf, uint8_t out_count)
	Drain conversion results for every channel mapped to a group.
ra8_err_t	ra8_adc_set_continuous_scan (uint8_t group, bool enable)
	Switch a scan group between one-shot and continuous (free-running).
ra8_err_t	ra8_adc_set_compare_window (uint8_t channel, uint16_t low, uint16_t high)
	Programme a window comparator for a single channel.
ra8_err_t	ra8_adc_set_oversampling (uint8_t channel, ra8_adc_oversample_t mode)
	Programme ADDOPCRB[ch].AVEMD/ADC for a per-channel averaging mode.

Variables
static const char *	s_tag = "ADC"
static ra8_adc_state_t	s_adc_state

Detailed Description

ADC16H (16-bit SAR) converter driver implementation.

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

Driver for the RA8 ADC_B peripheral – the 16-bit ADC16H SAR block shared byte-for-byte by the RA8D2 and RA8P1. Its register layout was cross-verified against FSP R_ADC_B0_Type (R7KA8D2KF_core0.h lines 20460-24938) and against the FSP driver in ra/fsp/src/r_adc_b/r_adc_b.c.

The bring-up sequence used here follows the FSP R_ADC_B_Open order:

Release MSTP gate (HUM Ch 11.2.9 MSTPCRD).
Disable ADCLK (write 0 to ADCLKENR), wait CLKSR == 0.
Programme ADCLKCR (clock source / divider).
Enable ADCLK (write 1 to ADCLKENR), wait CLKSR == 1.
Programme ADMDR per-unit operating mode (ADMD0[3:0], ADMD1[11:8]).
Programme each ADCHCRn slot (channel selection) and each ADDOPCRCn.ADPRC data-format (conversion resolution).
Enable scan-group via ADSGER, kick via ADSYSTR / ADSTR.
Poll ADSR.ADACT0/1, read ADDR[ch].

Conversion resolution (10/12/14/16-bit) is the per-channel ADDOPCRCn.ADPRC[1:0] data-format field (HUM Ch 53.2.3.4 p 3339), NOT an ADMDR mode: ADMDR.ADMD0 only selects the unit's operating mode (single-shot / one-cycle / continuous). The previous version of this driver modelled non-existent ADCSR / ADCER / RESSEL / CVEN bits and folded "resolution" into the ADMD0 mode code; both were wrong and have been deleted.

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

Definition in file adc.c.

Enumeration Type Documentation

◆ ra8_adc_default_group_t

enum ra8_adc_default_group_t : uint8_t

Scan-group used by the legacy single-channel polling API.

Enumerator
k_ra8_adc_default_group	Group 0 owns SW-trigger conversions.

Definition at line 56 of file adc.c.

Function Documentation

◆ internal_adprc_for_resolution()

bool internal_adprc_for_resolution	(	ra8_adc_resolution_t	resolution,
		uint32_t *	out_adprc )

static

Translate a public resolution selector into its ADDOPCRC.ADPRC code.

Conversion resolution on the ADC16H is the per-channel ADDOPCRCn.ADPRC[1:0] data-format field (HUM Ch 53.2.3.4 p 3339), not an ADMDR mode. This maps each ra8_adc_resolution_t selector onto the matching ra8_addopcrc_adprc_t code; an unknown selector is rejected so callers can fail cleanly.

Parameters

[in]	resolution	Public resolution selector.
[out]	out_adprc	Receives the ADPRC[1:0] code on success.

Returns: True when resolution is a known selector, false otherwise.

Return values

true	`resolution` is known; `out_adprc` holds the ADPRC code.
false	`resolution` is out of range; `out_adprc` left untouched.

Precondition: out_adprc is non-null.; resolution is sourced from ra8_adc_resolution_t.

Postcondition: out_adprc is written only when the function returns true.; No registers are accessed (pure translation).

Note: Re-entrant; touches no globals or MMIO.

Since: 0.1.0

Definition at line 112 of file adc.c.

References k_ra8_adc_res_10bit, k_ra8_adc_res_12bit, k_ra8_adc_res_14bit, k_ra8_adc_res_16bit, k_ra8_addopcrc_adprc_10bit, k_ra8_addopcrc_adprc_12bit, k_ra8_addopcrc_adprc_14bit, k_ra8_addopcrc_adprc_16bit, and RA8_INTERNAL.

Referenced by ra8_adc_init_configured(), and ra8_adc_set_resolution().

◆ internal_apply_group_enable()

void internal_apply_group_enable	(	uint8_t	group,
		ra8_adc_trigger_src_t	trigger )

static

Apply the per-group enable bit (ADSGER) and trigger source (ADTRGENR).

See implementation.

Parameters

[in]	group	See implementation.
[in]	trigger	See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 679 of file adc.c.

References k_ra8_adc_trig_src_software, ra8_adc_b_adsger(), ra8_adc_b_adtrgenr(), and RA8_INTERNAL.

Referenced by ra8_adc_configure_scan_group().

◆ internal_apply_resolution_code()

void internal_apply_resolution_code ( uint32_t adprc )

static

Install one ADPRC data-format code on every result-producing channel.

Programs adprc into each ADDOPCRC[0..k_ra8_adc_b_result_regs-1] slot so a conversion on any result channel reports in the matching precision. The dedicated self-diagnosis slot (top ADCHCR index) is deliberately excluded – ra8_adc_self_diagnose forces its own 16-bit signed format per run. The caller is responsible for validating the resolution -> ADPRC translation.

Parameters

[in] adprc ADPRC[1:0] data-format code (ra8_addopcrc_adprc_t).

Precondition: adprc is a valid ADPRC data-format code.; The ADC clock is running (init has completed).

Postcondition: Every result-channel ADDOPCRCn.ADPRC == adprc.; No slot outside 0..result_regs-1 is modified.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 182 of file adc.c.

References internal_write_adprc(), k_ra8_adc_b_result_regs, and RA8_INTERNAL.

Referenced by ra8_adc_init(), ra8_adc_init_configured(), and ra8_adc_set_resolution().

◆ internal_build_admdr()

uint32_t internal_build_admdr ( bool scan_mode )

static

Build the ADMDR value (ADMD0 only – ADC1 stays disabled).

ADMDR.ADMD0[3:0] selects the ADC0 operating mode: continuous scan when scan_mode is set, one-cycle scan otherwise. Conversion resolution is orthogonal (ADDOPCRC.ADPRC) and is not encoded here.

Parameters

[in] scan_mode True for continuous scan, false for one-shot.

Returns: Composite ADMDR value (ADMD0 field only).

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 316 of file adc.c.

References k_ra8_admdr_bit_admd0, k_ra8_admdr_mask_admd0, k_ra8_admdr_mode_continuous, k_ra8_admdr_mode_one_cycle, and RA8_INTERNAL.

Referenced by ra8_adc_init(), and ra8_adc_init_configured().

◆ internal_cache_group_channels()

void internal_cache_group_channels	(	uint8_t	group,
		const ra8_adc_scan_group_cfg_t *	cfg )

static

Cache a group's channel list into s_adc_state.groups.

See implementation.

Parameters

[in]	group	See implementation.
[in]	cfg	See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 657 of file adc.c.

References ra8_adc_scan_group_cfg_t::channels, ra8_adc_scan_group_cfg_t::num_channels, RA8_INTERNAL, and s_adc_state.

Referenced by ra8_adc_configure_scan_group().

◆ internal_clock_bring_up()

void internal_clock_bring_up ( uint32_t clkcr_value )

static

Bring ADCLK up: ENR=0 -> wait CLKSR=0 -> CR=src -> ENR=1 -> CLKSR=1.

Parameters

[in] clkcr_value ADCLKCR value to programme (CLKSEL[1:0], DIVR[18:16]).

See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 231 of file adc.c.

References internal_wait_clksr(), k_ra8_adclkenr_mask_clken, k_ra8_adclksr_mask_clksr, ra8_adc_b_adclkcr(), ra8_adc_b_adclkenr(), and RA8_INTERNAL.

Referenced by ra8_adc_init(), and ra8_adc_init_configured().

◆ internal_oversample_encode()

ra8_err_t internal_oversample_encode	(	ra8_adc_oversample_t	mode,
		uint32_t *	out_avemd,
		uint32_t *	out_adc )

static

Translate the public oversampling enum into ADDOPCRB AVEMD/ADC.

Parameters

[in]	mode	Public oversampling selector.
[out]	out_avemd	AVEMD field value (00 = off, 10 = average).
[out]	out_adc	ADC averaging-times code.

Returns: k_ra8_ok on success, k_ra8_err_invalid_arg for unknown modes.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 584 of file adc.c.

References k_ra8_adc_avg_16x, k_ra8_adc_avg_1x, k_ra8_adc_avg_4x, k_ra8_adc_avg_64x, k_ra8_adc_oversample_16x, k_ra8_adc_oversample_4x, k_ra8_adc_oversample_64x, k_ra8_adc_oversample_off, k_ra8_avemd_average, k_ra8_avemd_off, k_ra8_err_invalid_arg, and k_ra8_ok.

Referenced by ra8_adc_set_oversampling().

◆ internal_program_channel()

void internal_program_channel	(	uint8_t	virtual_ch,
		uint8_t	physical_ch )

static

Programme an ADCHCRn slot to map a physical channel into the default scan group with no special sample-and-hold.

Parameters

[in]	virtual_ch	Index of the ADCHCR slot to programme (0..23).
[in]	physical_ch	Physical analog channel selector (0..127).

See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 283 of file adc.c.

References k_ra8_adc_default_group, k_ra8_adchcr_bit_cnvcs, k_ra8_adchcr_bit_sgsel, k_ra8_adchcr_mask_cnvcs, k_ra8_adchcr_mask_sgsel, ra8_adc_b_adchcr(), and RA8_INTERNAL.

Referenced by ra8_adc_read_channel().

◆ internal_program_group_channels()

ra8_err_t internal_program_group_channels	(	uint8_t	group,
		const ra8_adc_scan_group_cfg_t *	cfg )

static

Walk the channel list and program ADCHCR[ch] = (SGSEL, CNVCS).

Parameters

[in]	group	Scan-group index (already validated).
[in]	cfg	Validated configuration descriptor.

Returns: k_ra8_ok or k_ra8_err_out_of_range if any ADCHCR slot is unmapped (defensive – channels were already range-checked).

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 625 of file adc.c.

References ra8_adc_scan_group_cfg_t::channels, k_ra8_adchcr_bit_cnvcs, k_ra8_adchcr_bit_sgsel, k_ra8_adchcr_mask_cnvcs, k_ra8_adchcr_mask_sgsel, k_ra8_err_out_of_range, k_ra8_ok, ra8_adc_scan_group_cfg_t::num_channels, ra8_adc_b_adchcr(), and RA8_INTERNAL.

Referenced by ra8_adc_configure_scan_group().

◆ internal_validate_group_cfg()

ra8_err_t internal_validate_group_cfg	(	uint8_t	group,
		const ra8_adc_scan_group_cfg_t *	cfg )

static

Validate a scan-group configuration descriptor.

Parameters

[in]	group	Scan-group index.
[in]	cfg	Non-NULL configuration descriptor.

Returns: k_ra8_ok on pass, otherwise an error code.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 549 of file adc.c.

References ra8_adc_scan_group_cfg_t::channels, k_ra8_adc_b_max_channels, k_ra8_adc_b_scan_groups, k_ra8_adc_scan_group_max_channels, k_ra8_err_out_of_range, k_ra8_ok, ra8_adc_scan_group_cfg_t::num_channels, and RA8_INTERNAL.

Referenced by ra8_adc_configure_scan_group().

◆ internal_wait_clksr()

void internal_wait_clksr ( uint32_t desired )

static

Best-effort wait for ADCLKSR.CLKSR to match the requested level.

On real silicon CLKSR follows ADCLKENR within a handful of cycles (HUM Ch 53). On the host ra8_fake_mmap window CLKSR is just anonymous RAM, so the wait is a bounded no-op. We mirror the FSP FSP_HARDWARE_REGISTER_WAIT pattern: poll a fixed budget and continue regardless rather than fail-loud.

Parameters

[in] desired Either k_ra8_adclksr_mask_clksr (running) or 0 (off).

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 208 of file adc.c.

References k_ra8_adc_clk_wait_limit, k_ra8_adclksr_mask_clksr, ra8_adc_b_adclksr(), and RA8_INTERNAL.

Referenced by internal_clock_bring_up().

◆ internal_write_adprc()

void internal_write_adprc	(	uint8_t	vch,
		uint32_t	adprc )

static

Write the ADPRC data-format field of one ADDOPCRCn slot (RMW).

Read-modify-writes ADDOPCRC[vch], replacing only ADPRC[1:0] and leaving SIGNSEL and the reserved bits intact (HUM Ch 53.2.3.4 p 3339). A slot whose accessor is out of range is skipped defensively.

Parameters

[in]	vch	Virtual-channel (ADDOPCRC) slot index.
[in]	adprc	ADPRC[1:0] data-format code to install.

Precondition: vch indexes a result-producing virtual channel.; adprc is sourced from ra8_addopcrc_adprc_t.

Postcondition: On a valid slot ADDOPCRCn.ADPRC == adprc.; No write occurs when vch is out of range.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 151 of file adc.c.

References k_ra8_addopcrc_bit_adprc, k_ra8_addopcrc_mask_adprc, ra8_adc_b_addopcrc(), and RA8_INTERNAL.

Referenced by internal_apply_resolution_code().

◆ internal_zero_channel_table()

void internal_zero_channel_table ( void )

static

Default-zero every per-channel ADCHCRn slot.

FSP R_ADC_B_Open clears every ADCHCRn before the user populates per-channel descriptors; we mirror that. This also ensures a stale CNVCS / SGSEL field cannot leak between configurations.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 257 of file adc.c.

References k_ra8_adc_b_max_channels, ra8_adc_b_adchcr(), and RA8_INTERNAL.

Referenced by ra8_adc_init(), and ra8_adc_init_configured().

◆ ra8_adc_attach_handler()

ra8_err_t ra8_adc_attach_handler	(	ra8_adc_complete_fn_t	fn,
		void *	ctx )

nodiscard

Attach a conversion-complete callback.

Parameters

[in]	fn	Non-NULL callback.
[in]	ctx	Context passed to the callback.

Returns: ra8_err_t error code.

Since: 0.1.0

Definition at line 485 of file adc.c.

References k_ra8_ok, and s_adc_state.

◆ ra8_adc_clear_status()

ra8_err_t ra8_adc_clear_status ( void )

nodiscard

Clear the ADCSR.ADST busy bit (abort in-flight conversion).

Returns: ra8_err_t error code.

Since: 0.1.0

Definition at line 473 of file adc.c.

References k_ra8_adstopr_mask_adstop0, k_ra8_adstopr_mask_adstop1, k_ra8_ok, ra8_adc_b_adsr(), and ra8_adc_b_adstopr().

◆ ra8_adc_configure_scan_group()

ra8_err_t ra8_adc_configure_scan_group	(	uint8_t	group,
		const ra8_adc_scan_group_cfg_t *	cfg )

nodiscard

Configure scan group group with a list of channels + trigger.

Programs every ADCHCR slot listed in cfg with SGSEL == group and CNVCS == the matching cfg->channels[i] entry, then enables the group via ADSGER. If cfg->trigger is non-software, the matching STTRGENn bit is set in ADTRGENR so the silicon edge-detector arms the group on the corresponding ELC / GPT / pin event.

Parameters

[in]	group	Scan-group index (0..8 inclusive on RA8D2).
[in]	cfg	Non-NULL configuration descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Group programmed.
k_ra8_err_null_ptr	`cfg` is NULL.
k_ra8_err_out_of_range	`group` >= 9 or any channel index >= 24 or `num_channels` not in 1..8.

Precondition: ra8_adc_init_configured (or ra8_adc_init) has been called.; IRQs masked or ADSTOPR cleared so we are not racing a scan.

Postcondition: ADSGER bit group is set.; Each listed ADCHCR slot has SGSEL == group and CNVCS == channels[i].

Note: Not thread-safe; caller serialises configuration.

See also: ra8_adc_start_group; ra8_adc_stop_group

Since: 0.1.0

Definition at line 691 of file adc.c.

References internal_apply_group_enable(), internal_cache_group_channels(), internal_program_group_channels(), internal_validate_group_cfg(), k_ra8_ok, ra8_adc_scan_group_cfg_t::priority, RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, s_tag, and ra8_adc_scan_group_cfg_t::trigger.

◆ ra8_adc_deinit()

ra8_err_t ra8_adc_deinit ( void )

nodiscard

Tear down the ADC_B peripheral.

Returns: ra8_err_t error code.

Postcondition: ADCSR == 0, ADCER == 0, MSTP released.

Since: 0.1.0

Definition at line 423 of file adc.c.

References k_ra8_adc_b_scan_groups, k_ra8_adstopr_mask_adstop0, k_ra8_adstopr_mask_adstop1, k_ra8_mstp_adc16h, ra8_adc_b_adclkenr(), ra8_adc_b_adcmpenr(), ra8_adc_b_adcmpintcr(), ra8_adc_b_adintcr(), ra8_adc_b_admdr(), ra8_adc_b_adsger(), ra8_adc_b_adstopr(), ra8_adc_b_adtrgenr(), ra8_mstp_disable(), and s_adc_state.

◆ ra8_adc_dispatch_cnv_end()

void ra8_adc_dispatch_cnv_end ( uint8_t channel )

Dispatch conversion-complete – read result + fire callback.

Parameters

[in] channel Channel the interrupt was reported on.

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 505 of file adc.c.

References k_ra8_addr_mask_data, ra8_adc_b_addr(), and s_adc_state.

◆ ra8_adc_enter_stop()

ra8_err_t ra8_adc_enter_stop ( void )

nodiscard

Put ADC_B into MSTP-gated stop.

Since: 0.1.0

Definition at line 492 of file adc.c.

References k_ra8_mstp_adc16h, ra8_adc_b_admdr(), and ra8_mstp_disable().

◆ ra8_adc_exit_stop()

ra8_err_t ra8_adc_exit_stop ( void )

nodiscard

Exit MSTP-gated stop.

Since: 0.1.0

Definition at line 499 of file adc.c.

References k_ra8_mstp_adc16h, and ra8_mstp_enable().

◆ ra8_adc_get_status()

ra8_err_t ra8_adc_get_status ( uint16_t * out_mask )

nodiscard

Read the ADC status bits (ADCSR.ADST / ADIE).

Parameters

[out] out_mask OR of k_ra8_adc_status_*.

Returns: ra8_err_t error code.

Since: 0.1.0

Definition at line 457 of file adc.c.

References k_ra8_adc_status_busy, k_ra8_adc_status_ie, k_ra8_adsr_mask_adact, k_ra8_ok, ra8_adc_b_adintcr(), ra8_adc_b_adsr(), RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_adc_init()

ra8_err_t ra8_adc_init ( void )

nodiscard

Legacy init – 14-bit right-aligned, software trigger.

Returns: ra8_err_t error code.

Since: 0.1.0

Definition at line 323 of file adc.c.

References internal_apply_resolution_code(), internal_build_admdr(), internal_clock_bring_up(), internal_zero_channel_table(), k_ra8_adc_b_scan_groups, k_ra8_adc_default_group, k_ra8_adc_res_14bit, k_ra8_addopcrc_adprc_14bit, k_ra8_mstp_adc16h, k_ra8_ok, ra8_adc_b_adintcr(), ra8_adc_b_admdr(), ra8_adc_b_adsger(), ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, s_adc_state, and s_tag.

Referenced by adc_diag_arm(), and ra8_nsc_adc_init().

◆ ra8_adc_init_configured()

ra8_err_t ra8_adc_init_configured ( const ra8_adc_cfg_t * cfg )

nodiscard

Initialise ADC_B with a full config descriptor.

Parameters

[in] cfg Non-NULL configuration descriptor.

Returns: ra8_err_t error code.

Precondition: IRQs masked or single-threaded init context.; ra8_mstp_init has been called.

Postcondition: On success ADCSR and ADCER match cfg and the ADC_B module is powered on via MSTP.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 387 of file adc.c.

References internal_adprc_for_resolution(), internal_apply_resolution_code(), internal_build_admdr(), internal_clock_bring_up(), internal_zero_channel_table(), k_ra8_adc_b_scan_groups, k_ra8_adc_default_group, k_ra8_err_invalid_arg, k_ra8_mstp_adc16h, k_ra8_ok, ra8_adc_b_adintcr(), ra8_adc_b_admdr(), ra8_adc_b_adsger(), RA8_CHECK_NULL_PTR, ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, ra8_adc_cfg_t::resolution, s_adc_state, s_tag, and ra8_adc_cfg_t::scan_mode.

Referenced by internal_arm().

◆ ra8_adc_read_channel()

ra8_err_t ra8_adc_read_channel	(	uint8_t	channel,
		uint16_t *	out_raw )

nodiscard

Blocking single-channel sample.

Parameters

[in]	channel	Analog channel index (0..47 on RA8D2 ADC_B).
[out]	out_raw	Pointer to receive the 14-bit result right-aligned.

Returns: ra8_err_t error code.

Since: 0.1.0

Definition at line 351 of file adc.c.

References internal_program_channel(), k_ra8_adc_busy_wait_limit, k_ra8_adc_default_group, k_ra8_addr_mask_data, k_ra8_adsr_mask_adact0, k_ra8_adstr_mask_adst, k_ra8_err_hw_timeout, k_ra8_err_out_of_range, k_ra8_ok, ra8_adc_b_adchcr(), ra8_adc_b_addr(), ra8_adc_b_adsr(), ra8_adc_b_adstr(), RA8_CHECK_NULL_PTR, ra8_log_error, and s_tag.

Referenced by main(), and ra8_nsc_adc_read_channel().

◆ ra8_adc_read_group_results()

ra8_err_t ra8_adc_read_group_results	(	uint8_t	group,
		uint16_t *	out_buf,
		uint8_t *	out_count )

nodiscard

Drain conversion results for every channel mapped to a group.

Walks the cached channel list captured by ra8_adc_configure_scan_group, reads ADDR[ch].DATA for each, and writes the masked 16-bit value into out_buf in order. out_count receives the number of channels written; it is also written on the error paths so callers can fail cleanly.

Parameters

[in]	group	Scan-group index (0..8).
[out]	out_buf	Result buffer, must hold cfg->num_channels entries.
[out]	out_count	Number of channels read.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Results copied.
k_ra8_err_null_ptr	`out_buf` or `out_count` is NULL.
k_ra8_err_out_of_range	`group` >= 9 or group never configured.

Since: 0.1.0

Definition at line 731 of file adc.c.

References ra8_adc_group_cache_t::channels, k_ra8_adc_b_scan_groups, k_ra8_addr_mask_data, k_ra8_err_out_of_range, k_ra8_ok, ra8_adc_group_cache_t::num_channels, ra8_adc_b_addr(), RA8_CHECK_NULL_PTR, s_adc_state, and s_tag.

◆ ra8_adc_set_compare_window()

ra8_err_t ra8_adc_set_compare_window	(	uint8_t	channel,
		uint16_t	low,
		uint16_t	high )

nodiscard

Programme a window comparator for a single channel.

Maps channel channel onto compare table channel (1:1 within the 0..7 supported table set), then writes:

ADCMPTBR[channel] = (high << 16) | low
ADCMPMDR{0,1}.CMPMD<channel> = inside-window mode (1)
ADCMPENR.CMPENn |= (1 << channel)
ADDOPCRB[channel].CMPTBLEm |= (1 << channel)

Parameters

[in]	channel	Channel / table index (0..7).
[in]	low	Low-side threshold.
[in]	high	High-side threshold (must be >= low).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Window programmed.
k_ra8_err_invalid_arg	`high` < `low`.
k_ra8_err_out_of_range	`channel` >= 8 (no compare table).

Since: 0.1.0

Definition at line 774 of file adc.c.

References k_ra8_adc_b_cmp_tables, k_ra8_adcmpmd_field_step, k_ra8_adcmpmd_inside, k_ra8_adcmpmd_per_reg, k_ra8_adcmptbr_bit_high, k_ra8_adcmptbr_bit_low, k_ra8_addopcrb_bit_cmptblem, k_ra8_addopcrb_mask_cmptblem, k_ra8_err_invalid_arg, k_ra8_err_out_of_range, k_ra8_ok, ra8_adc_b_adcmpenr(), ra8_adc_b_adcmpmdr(), ra8_adc_b_adcmptbr(), and ra8_adc_b_addopcrb().

◆ ra8_adc_set_continuous_scan()

ra8_err_t ra8_adc_set_continuous_scan	(	uint8_t	group,
		bool	enable )

nodiscard

Switch a scan group between one-shot and continuous (free-running).

Maps onto ADMDR.ADMD0: code k_ra8_admdr_mode_continuous when enable is true, k_ra8_admdr_mode_one_cycle otherwise. The group argument is currently advisory because ADMDR is per-unit (ADC0/ADC1), not per scan-group; future silicon revisions may add a per-group bit.

Parameters

[in]	group	Scan-group index (0..8).
[in]	enable	True for continuous scan, false for one-shot.

Returns: ra8_err_t error code.

Since: 0.1.0

Definition at line 757 of file adc.c.

References k_ra8_adc_b_scan_groups, k_ra8_admdr_bit_admd0, k_ra8_admdr_mask_admd0, k_ra8_admdr_mode_continuous, k_ra8_admdr_mode_one_cycle, k_ra8_err_out_of_range, k_ra8_ok, and ra8_adc_b_admdr().

◆ ra8_adc_set_oversampling()

ra8_err_t ra8_adc_set_oversampling	(	uint8_t	channel,
		ra8_adc_oversample_t	mode )

nodiscard

Programme ADDOPCRB[ch].AVEMD/ADC for a per-channel averaging mode.

Parameters

[in]	channel	Virtual-channel index (0..23).
[in]	mode	Logical oversampling rate.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Mode applied.
k_ra8_err_invalid_arg	`mode` not in ra8_adc_oversample_t.
k_ra8_err_out_of_range	`channel` >= 24.

Since: 0.1.0

Definition at line 819 of file adc.c.

References internal_oversample_encode(), k_ra8_addopcrb_bit_adc, k_ra8_addopcrb_bit_avemd, k_ra8_addopcrb_mask_adc, k_ra8_addopcrb_mask_avemd, k_ra8_err_out_of_range, k_ra8_ok, ra8_adc_b_addopcrb(), RA8_RETURN_ON_ERROR, and s_tag.

◆ ra8_adc_set_resolution()

ra8_err_t ra8_adc_set_resolution ( ra8_adc_resolution_t resolution )

nodiscard

Change the ADC conversion resolution at runtime.

Translates resolution into its ADDOPCRCn.ADPRC[1:0] data-format code (HUM Ch 53.2.3.4 p 3339) and programs it into every result-producing virtual channel's ADDOPCRCn, so the next conversion on any of those channels reports in the requested precision. The dedicated self-diagnosis slot is left untouched – ra8_adc_self_diagnose forces its own format.

Parameters

[in] resolution New resolution selector (ra8_adc_resolution_t).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	ADPRC updated on every result channel.
k_ra8_err_invalid_arg	`resolution` is not a known selector.

Precondition: ra8_adc_init (or ra8_adc_init_configured) has been called.; IRQs masked or single-threaded so no scan races the ADDOPCRC writes.

Postcondition: On success every result-channel ADDOPCRCn.ADPRC matches resolution.; On the error path no register is modified.

Note: Not thread-safe.

See also: ra8_adc_resolution_t

Since: 0.1.0

Definition at line 443 of file adc.c.

References internal_adprc_for_resolution(), internal_apply_resolution_code(), k_ra8_err_invalid_arg, k_ra8_ok, and s_adc_state.

◆ ra8_adc_start_group()

ra8_err_t ra8_adc_start_group ( uint8_t group )

nodiscard

Kick a scan group via the per-group ADSTR register.

Parameters

[in] group Scan-group index (0..8).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Group started.
k_ra8_err_out_of_range	`group` >= 9.

Precondition: Group has been configured via ra8_adc_configure_scan_group.

Postcondition: ADSTR[group].ADST == 1.

Since: 0.1.0

Definition at line 708 of file adc.c.

References k_ra8_adstr_mask_adst, k_ra8_err_out_of_range, k_ra8_ok, and ra8_adc_b_adstr().

◆ ra8_adc_stop_group()

ra8_err_t ra8_adc_stop_group ( uint8_t group )

nodiscard

Stop a scan group: clear ADSTR[group] and write ADSTOPR.

Parameters

[in] group Scan-group index (0..8).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Group stop requested.
k_ra8_err_out_of_range	`group` >= 9.

Postcondition: ADSTR[group].ADST == 0.; ADSTOPR.ADSTOP0|ADSTOP1 written so silicon force-stops both units.

Since: 0.1.0

Definition at line 719 of file adc.c.

References k_ra8_adstopr_mask_adstop0, k_ra8_adstopr_mask_adstop1, k_ra8_err_out_of_range, k_ra8_ok, ra8_adc_b_adstopr(), and ra8_adc_b_adstr().

Variable Documentation

◆ s_adc_state

ra8_adc_state_t s_adc_state

static

Definition at line 87 of file adc.c.

Referenced by internal_cache_group_channels(), ra8_adc_attach_handler(), ra8_adc_deinit(), ra8_adc_dispatch_cnv_end(), ra8_adc_init(), ra8_adc_init_configured(), ra8_adc_read_group_results(), and ra8_adc_set_resolution().

◆ s_tag

const char* s_tag = "ADC"

static

Definition at line 50 of file adc.c.

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_adc_default_group_t

Function Documentation

◆ internal_adprc_for_resolution()

◆ internal_apply_group_enable()

◆ internal_apply_resolution_code()

◆ internal_build_admdr()

◆ internal_cache_group_channels()

◆ internal_clock_bring_up()

◆ internal_oversample_encode()

◆ internal_program_channel()

◆ internal_program_group_channels()

◆ internal_validate_group_cfg()

◆ internal_wait_clksr()

◆ internal_write_adprc()

◆ internal_zero_channel_table()

◆ ra8_adc_attach_handler()

◆ ra8_adc_clear_status()

◆ ra8_adc_configure_scan_group()

◆ ra8_adc_deinit()

◆ ra8_adc_dispatch_cnv_end()

◆ ra8_adc_enter_stop()

◆ ra8_adc_exit_stop()

◆ ra8_adc_get_status()

◆ ra8_adc_init()

◆ ra8_adc_init_configured()

◆ ra8_adc_read_channel()

◆ ra8_adc_read_group_results()

◆ ra8_adc_set_compare_window()

◆ ra8_adc_set_continuous_scan()

◆ ra8_adc_set_oversampling()

◆ ra8_adc_set_resolution()

◆ ra8_adc_start_group()

◆ ra8_adc_stop_group()

Variable Documentation

◆ s_adc_state

◆ s_tag