Full-featured ADC_B driver. More...

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

Include dependency graph for ra8_adc.h:

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

Data Structures
struct	ra8_adc_cfg_t
	Configuration descriptor for ra8_adc_init_configured. More...
struct	ra8_adc_scan_group_cfg_t
	Configuration for a single scan group. More...

Typedefs
typedef void(*	ra8_adc_complete_fn_t) (void *ctx, uint16_t result)
	Conversion-complete callback.

Enumerations
enum	ra8_adc_resolution_t : uint8_t { k_ra8_adc_res_16bit = 0U , k_ra8_adc_res_14bit = 1U , k_ra8_adc_res_12bit = 2U , k_ra8_adc_res_10bit = 3U }
	ADDOPCRCn.ADPRC per-channel conversion-resolution (data-format) selector. More...
enum	ra8_adc_trigger_t : uint8_t { k_ra8_adc_trig_software = 0U , k_ra8_adc_trig_external = 1U , k_ra8_adc_trig_elc = 2U }
	ADCSR trigger mode. More...
enum	ra8_adc_status_mask_t : uint16_t { k_ra8_adc_status_none = 0x0000U , k_ra8_adc_status_busy = 0x8000U , k_ra8_adc_status_ie = 0x1000U }
	ADCSR status mask. More...
enum	ra8_adc_trigger_src_t : uint8_t { k_ra8_adc_trig_src_software = 0U , k_ra8_adc_trig_src_elc = 1U , k_ra8_adc_trig_src_gpt = 2U , k_ra8_adc_trig_src_pin = 3U }
	Per-scan-group trigger source. More...
enum	ra8_adc_priority_t : uint8_t { k_ra8_adc_priority_low = 0U , k_ra8_adc_priority_high = 1U }
	Scan-group priority class (FSP scan_group_priority). More...
enum	ra8_adc_oversample_t : uint8_t { k_ra8_adc_oversample_off = 0U , k_ra8_adc_oversample_4x = 1U , k_ra8_adc_oversample_16x = 2U , k_ra8_adc_oversample_64x = 3U }
	Per-channel ADADC.AVEMD/ADC oversampling configuration. More...
enum	ra8_adc_scan_group_caps_t : uint8_t { k_ra8_adc_scan_group_max_channels = 8U }
	Per-scan-group capacity limits for the ADC scan model. More...
enum	ra8_adc_selfdiag_mode_t : uint8_t { k_ra8_adc_selfdiag_mode_1 = 1U , k_ra8_adc_selfdiag_mode_2 = 2U , k_ra8_adc_selfdiag_mode_3 = 3U }
	ADC_B built-in self-diagnosis modes (HUM Ch 53.3.11 p 3411-3414). More...
enum	ra8_adc_internal_chan_t : uint8_t { k_ra8_adc_chan_temperature = 0x64U , k_ra8_adc_chan_int_ref_volt = 0x65U }
	Internal / extended-analog channels readable through the HAL. More...

Functions
ra8_err_t	ra8_adc_init (void)
	Legacy init – 14-bit right-aligned, software trigger.
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_read_channel (uint8_t channel, uint16_t *out_raw)
	Blocking single-channel sample.
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.
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.
ra8_err_t	ra8_adc_self_diagnose (ra8_adc_selfdiag_mode_t mode, uint16_t out_code, bool out_pass)
	Run an ADC_B built-in self-diagnosis pass on A/D unit 0.
ra8_err_t	ra8_adc_read_internal_channel (ra8_adc_internal_chan_t chan, uint16_t *out_raw)
	Blocking single conversion of an internal / extended-analog channel.

Detailed Description

Full-featured ADC_B driver.

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

Full build-out of the RA8 ADC16H peripheral (the 16-bit SAR block shared byte-for-byte by the RA8D2 and RA8P1). Extends the polling stub with: descriptor-based init, deinit, runtime resolution reconfigure (ADDOPCRCn.ADPRC per-channel data-format), status + clear, interrupt-mode attach / dispatch, power transition.

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

Definition in file ra8_adc.h.

Typedef Documentation

◆ ra8_adc_complete_fn_t

typedef void(* ra8_adc_complete_fn_t) (void *ctx, uint16_t result)

Conversion-complete callback.

Parameters

[in]	ctx	Caller context.
[in]	result	Last conversion result (raw ADDRxx).

Definition at line 98 of file ra8_adc.h.

Enumeration Type Documentation

◆ ra8_adc_internal_chan_t

enum ra8_adc_internal_chan_t : uint8_t

Internal / extended-analog channels readable through the HAL.

CNVCS[6:0] codes for on-chip analog sources (HUM Ch 53.2.3.1 Table p 3335). Their conversion result is read from the matching ADEXDRn register, not from ADDR[n] (HUM Ch 53.2.13.2 p 3391). The numeric values match ra8_adc_b_ext_chan_t in ra8_adc_b_regs.h; a static_assert in adc.c guards against drift.

See also: ra8_adc_read_internal_channel

Enumerator
k_ra8_adc_chan_temperature	On-chip die-temperature sensor.
k_ra8_adc_chan_int_ref_volt	Internal reference voltage.

Definition at line 535 of file ra8_adc.h.

◆ ra8_adc_oversample_t

enum ra8_adc_oversample_t : uint8_t

Per-channel ADADC.AVEMD/ADC oversampling configuration.

Maps a logical oversampling rate onto the (AVEMD, ADC) pair in ADDOPCRB[ch]:

off -> AVEMD=0
4x -> AVEMD=2 (average), ADC=2 (4 conversions)
16x -> AVEMD=2, ADC=4
64x -> AVEMD=2, ADC=6

Enumerator
k_ra8_adc_oversample_off	Single sample, no averaging.
k_ra8_adc_oversample_4x	4-sample average.
k_ra8_adc_oversample_16x	16-sample average.
k_ra8_adc_oversample_64x	64-sample average.

Definition at line 150 of file ra8_adc.h.

◆ ra8_adc_priority_t

enum ra8_adc_priority_t : uint8_t

Scan-group priority class (FSP scan_group_priority).

The RA8D2 ADC_B routes scan groups through a priority arbiter when multiple groups are armed at once; "high" preempts "low". The driver caches the priority but does not currently emit a register write because the priority routing in HUM Ch 53 lives in registers we have not modelled (scan_group_priority + interrupt_routing). The class is stored so future revisions can wire the missing registers without changing the public surface.

Enumerator
k_ra8_adc_priority_low	RA8 ADC priority low.
k_ra8_adc_priority_high	RA8 ADC priority high.

Definition at line 133 of file ra8_adc.h.

◆ ra8_adc_resolution_t

enum ra8_adc_resolution_t : uint8_t

ADDOPCRCn.ADPRC per-channel conversion-resolution (data-format) selector.

The RA8 ADC16H sets conversion precision per virtual channel through the ADDOPCRCn.ADPRC[1:0] data-format field (HUM Ch 53.2.3.4 p 3339), NOT through any unit-wide ADMDR mode. The driver translates each selector below into its ADPRC code and programs it into every result-producing channel's ADDOPCRCn. The full 16-bit range is the headline RA8P1 ADC16H capability; the RA8D2 exposes the same block and the identical register set. The 12-bit code that legacy FSP comments assumed is just one point on this selector, not a fixed hardware limit.

Invariant: Each value maps 1:1 onto a ra8_addopcrc_adprc_t code.

See also: ra8_adc_set_resolution; ra8_addopcrc_adprc_t

Enumerator
k_ra8_adc_res_16bit	16-bit conversion result (ADPRC = 0b00).
k_ra8_adc_res_14bit	14-bit conversion result (ADPRC = 0b01).
k_ra8_adc_res_12bit	12-bit conversion result (ADPRC = 0b10).
k_ra8_adc_res_10bit	10-bit conversion result (ADPRC = 0b11).

Definition at line 49 of file ra8_adc.h.

◆ ra8_adc_scan_group_caps_t

enum ra8_adc_scan_group_caps_t : uint8_t

Per-scan-group capacity limits for the ADC scan model.

Enumerator
k_ra8_adc_scan_group_max_channels	Maximum channels per scan group.

Definition at line 161 of file ra8_adc.h.

◆ ra8_adc_selfdiag_mode_t

enum ra8_adc_selfdiag_mode_t : uint8_t

ADC_B built-in self-diagnosis modes (HUM Ch 53.3.11 p 3411-3414).

The converter can inject one of three internal reference levels into the SAR core and compare the conversion result against a known ideal, proving the SAR + reference are healthy without external stimulus. The numeric ideal (16-bit signed) for each mode is tabulated in HUM Table 53.19 (p 3412):

Mode 1: both inputs at VREFL0 -> differential 0 -> 0x0000.
Mode 2: AINP=VREFL0, AINN=VREFH0 -> negative FS -> 0x8000 (-32768).
Mode 3: AINP=VREFH0, AINN=VREFL0 -> positive FS -> 0x7FFF (+32767).

See also: ra8_adc_self_diagnose

Enumerator
k_ra8_adc_selfdiag_mode_1	Zero-differential reference.
k_ra8_adc_selfdiag_mode_2	Negative full-scale.
k_ra8_adc_selfdiag_mode_3	Positive full-scale.

Definition at line 516 of file ra8_adc.h.

◆ ra8_adc_status_mask_t

enum ra8_adc_status_mask_t : uint16_t

ADCSR status mask.

Enumerator
k_ra8_adc_status_none	RA8 ADC status none.
k_ra8_adc_status_busy	ADCSR.ADST (conversion in flight).
k_ra8_adc_status_ie	ADCSR.ADIE.

Definition at line 86 of file ra8_adc.h.

◆ ra8_adc_trigger_src_t

enum ra8_adc_trigger_src_t : uint8_t

Per-scan-group trigger source.

Selects which event kicks the scan group:

software - call ra8_adc_start_group.
elc / gpt / pin - hardware path; ADTRGENR.STTRGENn must be set so the silicon edge-detector arms the group.

The selector value is observable via ra8_adc_b_adtrgenr() – the driver writes a 1 bit at group when the source is non-software.

Enumerator
k_ra8_adc_trig_src_software	SW kick (default).
k_ra8_adc_trig_src_elc	ELC event mux.
k_ra8_adc_trig_src_gpt	GPT compare-match.
k_ra8_adc_trig_src_pin	Hardware trigger pin.

Definition at line 113 of file ra8_adc.h.

◆ ra8_adc_trigger_t

enum ra8_adc_trigger_t : uint8_t

ADCSR trigger mode.

Enumerator
k_ra8_adc_trig_software	Software trigger (write ADST).
k_ra8_adc_trig_external	External trigger pin.
k_ra8_adc_trig_elc	ELC event routed trigger.

Definition at line 60 of file ra8_adc.h.

Function Documentation

◆ 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_read_internal_channel()

ra8_err_t ra8_adc_read_internal_channel	(	ra8_adc_internal_chan_t	chan,
		uint16_t *	out_raw )

nodiscard

Blocking single conversion of an internal / extended-analog channel.

Maps chan (e.g. temperature sensor CNVCS = 0x64) onto a dedicated virtual channel in single-ended mode, forces the 12-bit unsigned data format, starts the dedicated scan group, polls ADSR.ADACT0, and reads the 12-bit code from the matching ADEXDRn register (n = CNVCS - 0x60, HUM Ch 53.2.13.2 p 3391).

Parameters

[in]	chan	Internal channel selector.
[out]	out_raw	Receives the masked conversion code.

Returns: ra8_err_t Status code.

Return values

k_ra8_ok	Conversion read into `out_raw`.
k_ra8_err_null_ptr	`out_raw` is nullptr.
k_ra8_err_invalid_arg	`chan` is not a supported internal channel.
k_ra8_err_hw_timeout	ADSR.ADACT0 never cleared.
k_ra8_err_out_of_range	The mapped ADEXDR slot does not exist.

Precondition: ra8_adc_init has been called.; For the temperature channel, ra8_tsn_init has routed the sensor to the ADC mux (TSCR.TSOE).

Postcondition: out_raw == 0 on every error path.; No scan-group state other than the dedicated diagnostic group is modified.

Note: Not thread-safe.

See also: ra8_adc_internal_chan_t

Since: 0.1.0

Definition at line 381 of file adc_selfdiag.c.

References internal_is_supported_ext_chan(), internal_program_ext_channel(), internal_set_data_format(), internal_start_and_wait(), k_ra8_adc_diag_group, k_ra8_adc_diag_vchan, k_ra8_addopcrc_adprc_12bit, k_ra8_addopcrc_signsel_unsigned, k_ra8_adexdr_mask_data, k_ra8_err_invalid_arg, k_ra8_err_out_of_range, k_ra8_ok, ra8_adc_b_adexdr(), ra8_adc_b_adexdr_index_for_chan(), ra8_adc_b_adsger(), RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by adc_diag_run_cycle(), and ra8_tsn_read_die_temp_milli_c().

◆ ra8_adc_self_diagnose()

ra8_err_t ra8_adc_self_diagnose	(	ra8_adc_selfdiag_mode_t	mode,
		uint16_t *	out_code,
		bool *	out_pass )

nodiscard

Run an ADC_B built-in self-diagnosis pass on A/D unit 0.

Implements the HUM Ch 53.3.11.1 procedure (p 3412):

Map the self-diagnosis channel (CNVCS = 0x60) onto a dedicated virtual channel in differential input mode (HUM Ch 53.2.3.1 p 3335-3336).
Force the 16-bit signed data format on that channel via ADDOPCRC (ADPRC = 0, SIGNSEL = 0) as required by HUM Ch 53.3.11.3 p 3414.
Set ADSGDCRn.DIAGVAL[2:0] for the dedicated scan group to the requested mode (HUM Ch 53.2.4.1 p 3340).
Start the scan group, poll ADSR.ADACT0, and read the result from ADEXDR0.DATA[15:0] plus its ERR flag (HUM Ch 53.2.13.2 p 3391).
Compare the signed result against the mode's ideal value (Table 53.19 p 3412) within a gross-fault tolerance band and clear DIAGVAL back to off so later normal scans are unaffected.

Parameters

[in]	mode	Self-diagnosis mode (1 / 2 / 3).
[out]	out_code	Raw 16-bit ADEXDR0 result code (signed value).
[out]	out_pass	True iff ERR == 0 and the result is within the expected-value tolerance band.

Returns: ra8_err_t Status code.

Return values

k_ra8_ok	Diagnosis ran (inspect `out_pass`).
k_ra8_err_null_ptr	`out_code` or `out_pass` is nullptr.
k_ra8_err_invalid_arg	`mode` is not 1 / 2 / 3.
k_ra8_err_hw_timeout	ADSR.ADACT0 never cleared.

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

Postcondition: ADSGDCRn.DIAGVAL for the dedicated diagnostic group is back to 0.; out_code and out_pass are written on every k_ra8_ok return.

Note: Not thread-safe; serialise with normal conversions.; Tolerance band is a gross-fault detector; tighten it to the HUM Ch 69 accuracy spec for production sign-off.

See also: ra8_adc_selfdiag_mode_t

Since: 0.1.0

Definition at line 351 of file adc_selfdiag.c.

References internal_diagval_for_mode(), internal_selfdiag_expected(), internal_selfdiag_in_band(), internal_selfdiag_run(), k_ra8_adc_b_chan_selfdiag_adc0, k_ra8_adc_b_ext_chan_base, k_ra8_adexdr_mask_data, k_ra8_adexdr_mask_err, k_ra8_err_invalid_arg, k_ra8_ok, ra8_adc_b_adexdr(), RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by adc_diag_run_cycle().

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

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_adc_complete_fn_t

Enumeration Type Documentation

◆ ra8_adc_internal_chan_t

◆ ra8_adc_oversample_t

◆ ra8_adc_priority_t

◆ ra8_adc_resolution_t

◆ ra8_adc_scan_group_caps_t

◆ ra8_adc_selfdiag_mode_t

◆ ra8_adc_status_mask_t

◆ ra8_adc_trigger_src_t

◆ ra8_adc_trigger_t

Function Documentation

◆ 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_read_internal_channel()

◆ ra8_adc_self_diagnose()

◆ 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()