On-chip Temperature Sensor (TSN) driver. More...

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

Include dependency graph for ra8_tsn.h:

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

Data Structures
struct	ra8_tsn_config_t
	Configuration descriptor for ra8_tsn_init. More...

Enumerations
enum	ra8_tsn_cal_temp_t : int16_t { k_ra8_tsn_cal_temp_high_125 = 125 , k_ra8_tsn_cal_temp_high_105 = 105 , k_ra8_tsn_cal_temp_low_n40 = -40 }
	Factory calibration reference temperatures (degC). More...

Functions
ra8_err_t	ra8_tsn_init (const ra8_tsn_config_t *cfg)
	Power on the TSN block and enable its ADC output path.
ra8_err_t	ra8_tsn_deinit (void)
	Tear down the TSN block.
ra8_err_t	ra8_tsn_read_raw (uint16_t raw, uint16_t *out_code)
	Pass through a raw ADC sample of the TSN channel.
ra8_err_t	ra8_tsn_convert_to_milli_c (uint16_t raw_code, int32_t *out_milli_c)
	Convert a raw 12-bit TSN code to milli-degrees-Celsius.
ra8_err_t	ra8_tsn_read_die_temp_milli_c (int32_t *out_milli_c)
	Read the die temperature end-to-end through the HAL.
ra8_err_t	ra8_tsn_get_status (uint8_t *out_tscr)
	Read TSCR (TSEN + TSOE bits).
ra8_err_t	ra8_tsn_clear_status (void)
	Clear TSCR (drive both TSEN and TSOE low).
ra8_err_t	ra8_tsn_enter_stop (void)
	Re-assert MSTPD22 to clock-gate the TSN block.
ra8_err_t	ra8_tsn_exit_stop (void)
	Clear MSTPD22 to re-power the TSN block.

Detailed Description

On-chip Temperature Sensor (TSN) driver.

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

Minimum-viable driver for the RA8D2 on-chip die-temperature sensor (HUM Ch 55, p 3497-3507). The block is tiny: the only peripheral-side register is TSCR (TSEN + TSOE bits) plus two read-only calibration words in MRAM (TSCDR, TSCDR2).

Surface

ra8_tsn_init() – clear MSTPD22, set TSCR.TSEN, busy-wait the 30 us reference-voltage stabilisation, then set TSCR.TSOE so the sensor output reaches the ADC16H input mux.
ra8_tsn_deinit() – clear TSOE, then TSEN, then re-assert the module-stop bit.
ra8_tsn_read_raw() – accepts a raw 12-bit ADC code read by the caller from the ADC and returns it back as an uint16_t (no driver-side ADC access, see "Scope" below).
ra8_tsn_convert_to_milli_c() – two-point trim conversion to degrees Celsius x 1000.
ra8_tsn_get_status() / ra8_tsn_clear_status() – read / clear TSCR enable bits.
ra8_tsn_enter_stop() / ra8_tsn_exit_stop() – MSTPD22 transitions.

Scope

This driver does NOT touch the ADC. HUM Ch 55.3.2 (p 3501) describes the full conversion procedure: configure the ADC for the temperature-sensor channel, start a conversion, then read the result. Callers are responsible for that side of the dance via libs/ra8_hal/src/adc.c (see ra8_adc_b_regs.h for the ADC channel-select bits). This driver only owns TSCR and the calibration math.

Not yet implemented

The TEMPRCR.TSNKEEP path (HUM Ch 6 "Resets") for surviving a low-power transition with the sensor still enabled. The HUM Ch 55.3.2 procedure mentions this register but it lives in the system controller; wiring it in requires the LPM / PRCR helpers from libs/ra8_hal/src/ra8_pwr.c.
Abnormal-temperature reset source (Table 55.1 row 4) – the output is a hardwired reset-circuit signal so the driver has no register to expose.
Single-point conversion (using only TSCDR + the typical slope from HUM Ch 69 "Electrical Characteristics"). Two-point trim is more accurate so the driver only ships that path.

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

Definition in file ra8_tsn.h.

Enumeration Type Documentation

◆ ra8_tsn_cal_temp_t

enum ra8_tsn_cal_temp_t : int16_t

Factory calibration reference temperatures (degC).

The RA8D2 family is shipped in three trim variants; the high-side reference is either 105 degC (95 / 105 degC Tj_max parts) or 125 degC (125 degC Tj_max parts), and the low-side reference is always -40 degC. The calibration code observed at each reference is programmed into TSCDR / TSCDR2 at the factory (HUM Ch 55.3.1 "Calculating the Temperature from the Output Voltage of the Temperature Sensor", p 3499-3500).

The numeric value of each enumerator is the temperature itself in signed degC – callers can cast directly to int16_t for the conversion math without a lookup table.

Invariant: Only the three enumerators below are accepted by ra8_tsn_init. Any other value is rejected with k_ra8_err_invalid_arg.

See also: ra8_tsn_config_t::high_ref_degc; ra8_tsn_config_t::low_ref_degc

Enumerator
k_ra8_tsn_cal_temp_high_125	125 degC Tj_max parts.
k_ra8_tsn_cal_temp_high_105	95 / 105 degC parts.
k_ra8_tsn_cal_temp_low_n40	Always -40 degC on RA8D2.

Definition at line 98 of file ra8_tsn.h.

Function Documentation

◆ ra8_tsn_clear_status()

ra8_err_t ra8_tsn_clear_status ( void )

nodiscard

Clear TSCR (drive both TSEN and TSOE low).

Returns: ra8_err_t Status code.

Return values

k_ra8_ok Always.

Precondition: TSN module-stop is cleared so the write actually lands.; Caller has accepted that this stops the sensor immediately.

Postcondition: TSCR == 0.; Sensor output is no longer driven onto the ADC mux.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 283 of file ra8_tsn.c.

References k_ra8_ok, ra8_tsn(), and r_tsn_ctrl_regs_t::TSCR.

◆ ra8_tsn_convert_to_milli_c()

ra8_err_t ra8_tsn_convert_to_milli_c	(	uint16_t	raw_code,
		int32_t *	out_milli_c )

nodiscard

Convert a raw 12-bit TSN code to milli-degrees-Celsius.

Two-point trim conversion (HUM Ch 55.3.1 p 3499-3500):

v1_uv = AVCC_uV * CAL_HI / 4096 v2_uv = AVCC_uV * CAL_LO / 4096 vs_uv = AVCC_uV * raw / 4096 T_mC = ((vs_uv - v1_uv) * (T1 - T2) * 1000) / (v1_uv - v2_uv)

T1 * 1000

Everything stays in 64-bit signed integer arithmetic so the driver can run on the Cortex-M85 without pulling in libm.

Parameters

[in]	raw_code	12-bit ADC code from ra8_tsn_read_raw.
[out]	out_milli_c	Temperature in milli-degC (+25000 = 25 degC).

Returns: ra8_err_t Status code.

Return values

k_ra8_ok	Conversion succeeded.
k_ra8_err_null_ptr	out_milli_c was nullptr.
k_ra8_err_invalid_state	ra8_tsn_init has not run, or the calibration words are 0 (would divide by zero).

Precondition: ra8_tsn_init has been called.; raw_code <= 0x0FFF.

Postcondition: *out_milli_c populated when the call returns k_ra8_ok.; No peripheral registers were written.

Note: Thread safety: re-entrant – reads MMIO only.

See also: ra8_tsn_read_raw

Since: 0.1.0

Definition at line 214 of file ra8_tsn.c.

References k_ra8_err_invalid_state, k_ra8_ok, k_ra8_tscdr_data_mask, k_ra8_tsn_adc_avcc_uv, k_ra8_tsn_adc_full_scale, k_ra8_tsn_uv_per_mv, RA8_CHECK_NULL_PTR, ra8_tsn_cal(), s_ra8_tsn_high_ref_degc, s_ra8_tsn_initialized, s_ra8_tsn_low_ref_degc, s_tag, r_tsn_cal_regs_t::TSCDR, and r_tsn_cal_regs_t::TSCDR2.

Referenced by ra8_tsn_read_die_temp_milli_c().

◆ ra8_tsn_deinit()

ra8_err_t ra8_tsn_deinit ( void )

nodiscard

Tear down the TSN block.

Clears TSCR.TSOE then TSCR.TSEN (HUM Figure 55.2 p 3502 reverse sequence) and then re-asserts MSTPD22 via ra8_mstp_disable.

Returns: ra8_err_t Status code.

Return values

k_ra8_ok	Sensor stopped and module-stop reasserted.
Other	Forwarded from ra8_mstp_disable.

Precondition: Caller has previously called ra8_tsn_init.; No outstanding ADC conversion targeting the TSN channel.

Postcondition: TSCR.TSEN = 0 and TSCR.TSOE = 0.; MSTPD22 is set (block clock-gated).

Note: Thread safety: not thread-safe.

See also: ra8_tsn_init

Since: 0.1.0

Definition at line 180 of file ra8_tsn.c.

References k_ra8_mstp_tsn, k_ra8_ok, k_ra8_tscr_mask_tsen, ra8_mstp_disable(), ra8_tsn(), s_ra8_tsn_initialized, and r_tsn_ctrl_regs_t::TSCR.

◆ ra8_tsn_enter_stop()

ra8_err_t ra8_tsn_enter_stop ( void )

nodiscard

Re-assert MSTPD22 to clock-gate the TSN block.

Returns: ra8_err_t Status code.

Return values

k_ra8_ok	Module-stop bit asserted.
Other	Forwarded from ra8_mstp_disable.

Precondition: Caller has stopped any in-flight ADC conversion that targets the TSN channel.; ra8_mstp_init has been called.

Postcondition: MSTPD22 = 1.; Subsequent TSCR reads return 0 until ra8_tsn_exit_stop.

Note: Thread safety: not thread-safe.

See also: ra8_tsn_exit_stop

Since: 0.1.0

Definition at line 291 of file ra8_tsn.c.

References k_ra8_mstp_tsn, and ra8_mstp_disable().

◆ ra8_tsn_exit_stop()

ra8_err_t ra8_tsn_exit_stop ( void )

nodiscard

Clear MSTPD22 to re-power the TSN block.

Returns: ra8_err_t Status code.

Return values

k_ra8_ok	Module-stop bit cleared.
Other	Forwarded from ra8_mstp_enable.

Precondition: ra8_mstp_init has been called.; Caller will re-run the TSEN / tTSTBL / TSOE sequence before reading any new conversion.

Postcondition: MSTPD22 = 0.; TSCR is back to its reset value (0).

Note: Thread safety: not thread-safe.

See also: ra8_tsn_enter_stop

Since: 0.1.0

Definition at line 297 of file ra8_tsn.c.

References k_ra8_mstp_tsn, and ra8_mstp_enable().

◆ ra8_tsn_get_status()

ra8_err_t ra8_tsn_get_status ( uint8_t * out_tscr )

nodiscard

Read TSCR (TSEN + TSOE bits).

Parameters

[out] out_tscr Receives the current TSCR value (only k_ra8_tscr_mask_all bits are valid).

Returns: ra8_err_t Status code.

Return values

k_ra8_ok	*out_tscr populated.
k_ra8_err_null_ptr	out_tscr was nullptr.

Precondition: TSN module-stop is cleared (otherwise the read returns 0).; out_tscr is non-null.

Postcondition: No registers were written.; *out_tscr populated when the call returns k_ra8_ok.

Note: Thread safety: re-entrant.

Since: 0.1.0

Definition at line 274 of file ra8_tsn.c.

References k_ra8_ok, k_ra8_tscr_mask_all, RA8_CHECK_NULL_PTR, ra8_tsn(), s_tag, and r_tsn_ctrl_regs_t::TSCR.

◆ ra8_tsn_init()

ra8_err_t ra8_tsn_init ( const ra8_tsn_config_t * cfg )

nodiscard

Power on the TSN block and enable its ADC output path.

Algorithm (HUM Figure 55.2 p 3502 condensed for the case where TEMPRCR.TSNKEEP is left at its reset value):

Validate cfg and the configured stabilisation delay.
Clear MSTPD22 via ra8_mstp_enable(k_ra8_mstp_tsn) (HUM Ch 11.2.9 p 449).
Set TSCR.TSEN = 1 to start the sensor.
Busy-wait cfg->stab_us microseconds (>= 30 us per the HUM tTSTBL spec).
Set TSCR.TSOE = 1 to route the sensor output to the ADC16H input mux. The ADC itself is not touched here – driving the ADC channel select stays the caller's job (see libs/ra8_hal/src/adc.c and the ADC chapter, HUM Ch 53).

Parameters

[in] cfg Non-null configuration descriptor.

Returns: ra8_err_t Status code.

Return values

k_ra8_ok	Sensor enabled and routed to the ADC.
k_ra8_err_null_ptr	cfg was nullptr.
k_ra8_err_invalid_arg	cfg->stab_us below the 30 us floor or calibration temperatures invalid.
Other	Forwarded from ra8_mstp_enable.

Precondition: IRQs masked or single-threaded init context.; ra8_mstp_init has been called.; AVCC0 / VREFH0 are stable (3.3 V).

Postcondition: TSCR.TSEN = 1 and TSCR.TSOE = 1.; The 30 us reference-voltage stabilisation has elapsed.

Note: Thread safety: not thread-safe; call once during init.; The driver does not start an ADC conversion. Callers must drive the ADC themselves.

Example:: const ra8_tsn_config_t cfg = {

.high_ref_degc = k_ra8_tsn_cal_temp_high_125,

.low_ref_degc = k_ra8_tsn_cal_temp_low_n40,

.stab_us = 30,

};

(void)ra8_tsn_init(&cfg);

ra8_tsn_init
ra8_err_t ra8_tsn_init(const ra8_tsn_config_t *cfg)
Power on the TSN block and enable its ADC output path.
Definition ra8_tsn.c:149

k_ra8_tsn_cal_temp_high_125
@ k_ra8_tsn_cal_temp_high_125
125 degC Tj_max parts.
Definition ra8_tsn.h:99

k_ra8_tsn_cal_temp_low_n40
@ k_ra8_tsn_cal_temp_low_n40
Always -40 degC on RA8D2.
Definition ra8_tsn.h:101

ra8_tsn_config_t
Configuration descriptor for ra8_tsn_init.
Definition ra8_tsn.h:121

See also: ra8_tsn_deinit; ra8_tsn_read_raw; ra8_tsn_convert_to_milli_c

Since: 0.1.0

Definition at line 149 of file ra8_tsn.c.

References ra8_tsn_config_t::high_ref_degc, internal_busy_wait_us(), internal_validate_cfg(), k_ra8_mstp_tsn, k_ra8_ok, k_ra8_tscr_mask_tsen, k_ra8_tscr_mask_tsoe, ra8_tsn_config_t::low_ref_degc, RA8_CHECK_NULL_PTR, ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, ra8_tsn(), s_ra8_tsn_high_ref_degc, s_ra8_tsn_initialized, s_ra8_tsn_low_ref_degc, s_tag, ra8_tsn_config_t::stab_us, and r_tsn_ctrl_regs_t::TSCR.

Referenced by adc_diag_arm().

◆ ra8_tsn_read_die_temp_milli_c()

ra8_err_t ra8_tsn_read_die_temp_milli_c ( int32_t * out_milli_c )

nodiscard

Read the die temperature end-to-end through the HAL.

Closes the loop that ra8_tsn_read_raw deliberately leaves to the caller: it drives the ADC16H temperature-sensor channel (CNVCS = 0x64, HUM Ch 53.2.3.1 Table p 3335) via ra8_adc_read_internal_channel, masks the raw 12-bit code through ra8_tsn_read_raw, then runs the two-point trim conversion (ra8_tsn_convert_to_milli_c). The result register for the temperature channel is ADEXDR4 (HUM Ch 53.2.13.2 p 3391); that routing lives in adc.c.

Parameters

[out] out_milli_c Temperature in milli-degC (+25000 = 25 degC).

Returns: ra8_err_t Status code.

Return values

k_ra8_ok	Temperature read and converted.
k_ra8_err_null_ptr	out_milli_c was nullptr.
k_ra8_err_invalid_state	ra8_tsn_init has not run, or the calibration words are unprogrammed.
k_ra8_err_hw_timeout	The ADC conversion never completed.
k_ra8_err_out_of_range	The temperature ADEXDR slot was unmapped.

Precondition: ra8_tsn_init has routed the sensor to the ADC mux (TSCR.TSOE).; ra8_adc_init has powered and clocked the ADC16H.

Postcondition: *out_milli_c populated when the call returns k_ra8_ok.; No TSN registers were written (only the ADC was driven).

Note: Thread safety: not thread-safe; serialise with other ADC use.

See also: ra8_tsn_convert_to_milli_c; ra8_tsn_read_raw

Since: 0.1.0

Definition at line 249 of file ra8_tsn.c.

References k_ra8_adc_chan_temperature, k_ra8_err_invalid_state, ra8_adc_read_internal_channel(), RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, ra8_tsn_convert_to_milli_c(), ra8_tsn_read_raw(), s_ra8_tsn_initialized, and s_tag.

Referenced by adc_diag_run_cycle().

◆ ra8_tsn_read_raw()

ra8_err_t ra8_tsn_read_raw	(	uint16_t	raw,
		uint16_t *	out_code )

nodiscard

Pass through a raw ADC sample of the TSN channel.

The TSN block has no result register of its own – the conversion code lives in the ADC's data register. The caller arms the ADC (see ra8_adc.h and ADC chapter HUM Ch 53), reads the raw 12-bit code, and hands it here. This function masks the value down to the documented 12-bit width and returns it via out_code. It exists so that future callers can be retargeted at a different conversion path (for example the high-resolution accumulator) without changing their call sites.

Parameters

[in]	raw	Raw ADC code as read from the ADC's data register. Only the lower 12 bits are observed (HUM Ch 55.2.2 p 3498-3499: calibration codes are 12-bit, so live samples are too).
[out]	out_code	Receives the masked 12-bit code.

Returns: ra8_err_t Status code.

Return values

k_ra8_ok	Code stored in *out_code.
k_ra8_err_null_ptr	out_code was nullptr.
k_ra8_err_invalid_state	TSCR.TSEN is 0 (sensor not started).

Precondition: ra8_tsn_init has been called.; Caller already obtained the raw ADC code.

Postcondition: *out_code <= 0x0FFF.; No registers were written.

Note: Thread safety: not thread-safe.

See also: ra8_tsn_convert_to_milli_c

Since: 0.1.0

Definition at line 202 of file ra8_tsn.c.

References k_ra8_err_invalid_state, k_ra8_ok, k_ra8_tscdr_data_mask, RA8_CHECK_NULL_PTR, s_ra8_tsn_initialized, and s_tag.

Referenced by ra8_tsn_read_die_temp_milli_c().

Data Structures

Enumerations

Functions

Detailed Description

Surface

Scope

Not yet implemented

Enumeration Type Documentation

◆ ra8_tsn_cal_temp_t

Function Documentation

◆ ra8_tsn_clear_status()

◆ ra8_tsn_convert_to_milli_c()

◆ ra8_tsn_deinit()

◆ ra8_tsn_enter_stop()

◆ ra8_tsn_exit_stop()

◆ ra8_tsn_get_status()

◆ ra8_tsn_init()

◆ ra8_tsn_read_die_temp_milli_c()

◆ ra8_tsn_read_raw()