Decryption On The Fly (DOTF) high-level open/close + power control. More...

#include <stdint.h>
#include "ra8_check.h"
#include "ra8_dotf.h"
#include "ra8_dotf_regs.h"
#include "ra8_err.h"
#include "ra8_hal_internal.h"
#include "ra8_log.h"
#include "ra8_mstp.h"

Include dependency graph for ra8_dotf_power.c:

Functions
static ra8_err_t	internal_open_validate_init (const ra8_dotf_open_cfg_t *cfg)
	Validate ra8_dotf_open inputs and power up the DOTF block.
static ra8_err_t	internal_open_stage_key_iv_region (const ra8_dotf_open_cfg_t *cfg)
	Stage the wrapped key, IV, and conversion region for ra8_dotf_open.
static ra8_err_t	internal_open_finalise (const ra8_dotf_open_cfg_t *cfg)
	Apply SCA level and (optionally) arm the AES core.
ra8_err_t	ra8_dotf_open (const ra8_dotf_open_cfg_t *cfg)
	One-shot DOTF bring-up: init + install_key + set_iv + set_region (+ enable).
ra8_err_t	ra8_dotf_close (void)
	Tear down DOTF and release all hardware state.
ra8_err_t	ra8_dotf_set_region_window (uint8_t channel, uint32_t start, uint32_t len)
	Stage a region from a (start, length) pair instead of a struct.
ra8_err_t	ra8_dotf_enter_stop (void)
	Park the DOTF block prior to entering a low-power mode.
ra8_err_t	ra8_dotf_exit_stop (void)
	Bring the DOTF block back from low-power mode.

Variables
static const char *	s_tag = "DOTF"
	Logging tag for ra8_log_* calls.
static const ra8_mstp_t	s_dotf_mstp_table [k_ra8_dotf_channel_count]
	Channel-index -> MSTP id lookup.

Detailed Description

Decryption On The Fly (DOTF) high-level open/close + power control.

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

High-level orchestration layer for the RA8D2 DOTF block, split out of ra8_dotf.c purely to keep each translation unit under the per-file size cap. Hosts the multi-step ra8_dotf_open bring-up sequence and its internal sub-steps, the symmetric ra8_dotf_close, the convenience window helper ra8_dotf_set_region_window, and the module-stop enter/exit pair. Every register / clock-gate access carries a HUM Ch 45 citation. See ra8_dotf.h for the public surface.

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

Since: 0.1.0

Definition in file ra8_dotf_power.c.

Function Documentation

◆ internal_open_finalise()

ra8_err_t internal_open_finalise ( const ra8_dotf_open_cfg_t * cfg )

staticnodiscard

Apply SCA level and (optionally) arm the AES core.

Internal sub-step of ra8_dotf_open. Performs step 6 (REG00 SCA bits via ra8_dotf_set_sca_level) and step 7 (gated by cfg->enable_after: arm the AES enable bit via ra8_dotf_enable). HUM Ch 45.3 "Register Descriptions" p 3049.

Parameters

[in] cfg Non-NULL caller-supplied open config (already validated).

Returns: ra8_err_t propagated from the underlying steps.

Return values

k_ra8_ok	SCA applied; AES armed if requested.
k_ra8_err_invalid_arg	Underlying primitive rejected input.

Precondition: cfg is non-NULL.; Key, IV, and region staging have already succeeded.

Postcondition: Cached SCA level reflects cfg->sca_level.; On k_ra8_ok and cfg->enable_after, REG00 has the AES enable bit set.

Note: Not thread-safe; sole caller is ra8_dotf_open.

See also: ra8_dotf_set_sca_level; ra8_dotf_enable

Since

Definition at line 190 of file ra8_dotf_power.c.

References ra8_dotf_open_cfg_t::channel, ra8_dotf_open_cfg_t::enable_after, k_ra8_ok, ra8_dotf_enable(), ra8_dotf_set_sca_level(), RA8_RETURN_ON_ERROR, s_tag, and ra8_dotf_open_cfg_t::sca_level.

Referenced by ra8_dotf_open().

◆ internal_open_stage_key_iv_region()

ra8_err_t internal_open_stage_key_iv_region ( const ra8_dotf_open_cfg_t * cfg )

staticnodiscard

Stage the wrapped key, IV, and conversion region for ra8_dotf_open.

Internal sub-step of ra8_dotf_open. Performs steps 2..5: wrapped-key install (HUM Ch 45.3 p 3049 REG03 staging), IV stage (HUM Ch 45.1 p 3048 counter mode), region descriptor stage (HUM Ch 45.3.1 / 45.3.2 p 3049), and live-region promotion via ra8_dotf_select_region.

Parameters

[in] cfg Non-NULL caller-supplied open config (already validated).

Returns: ra8_err_t propagated from the underlying steps.

Return values

k_ra8_ok	Key, IV, and region all staged.
k_ra8_err_invalid_arg	Underlying primitive rejected input.
k_ra8_err_conflict	Region overlaps live region of other channel.
k_ra8_err_invalid_state	ra8_dotf_select_region rejected.

Precondition: cfg is non-NULL and has passed internal_open_validate_init.; DOTF MSTP gate is open for cfg->channel.

Postcondition: On k_ra8_ok REG03 holds wrapped key + IV, CONVAREAST/ED reflect the requested region, and s_dotf_state[ch].active_region_id equals cfg->region.region_id.

Note: Not thread-safe; sole caller is ra8_dotf_open.

See also: ra8_dotf_install_key; ra8_dotf_set_iv; ra8_dotf_set_region; ra8_dotf_select_region

Since

Definition at line 137 of file ra8_dotf_power.c.

References ra8_dotf_open_cfg_t::channel, ra8_dotf_open_cfg_t::iv_words, k_ra8_ok, ra8_dotf_open_cfg_t::key, ra8_dotf_install_key(), ra8_dotf_select_region(), ra8_dotf_set_iv(), ra8_dotf_set_region(), RA8_RETURN_ON_ERROR, ra8_dotf_open_cfg_t::region, ra8_dotf_region_t::region_id, and s_tag.

Referenced by ra8_dotf_open().

◆ internal_open_validate_init()

ra8_err_t internal_open_validate_init ( const ra8_dotf_open_cfg_t * cfg )

staticnodiscard

Validate ra8_dotf_open inputs and power up the DOTF block.

Internal sub-step of ra8_dotf_open. Extracted so the public entry point stays under the NASA Rule 4 / clang-tidy readability-function-size and readability-function-cognitive-complexity thresholds without requiring an inline lint override.

Sequence:

Range-check cfg->channel.
Idempotently power on both DOTF channels via ra8_dotf_init (HUM Ch 45.6.1 p 3050).

Parameters

[in] cfg Non-NULL caller-supplied open config.

Returns: ra8_err_t propagated from the underlying steps.

Return values

k_ra8_ok	Channel valid, DOTF block powered.
k_ra8_err_invalid_arg	cfg->channel out of range.
k_ra8_err_hw_init_failed	Channel-base mapping failed.

Precondition: cfg is non-NULL.; Caller is single-threaded (driver bring-up context).

Postcondition: On k_ra8_ok MSTPB16/17 are ungated for both channels.

Note: Not thread-safe; sole caller is ra8_dotf_open.

See also: ra8_dotf_init

Since

Definition at line 92 of file ra8_dotf_power.c.

References ra8_dotf_open_cfg_t::channel, internal_ra8_dotf_internal_channel_in_range(), k_ra8_err_invalid_arg, k_ra8_ok, ra8_dotf_init(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by ra8_dotf_open().

◆ ra8_dotf_close()

ra8_err_t ra8_dotf_close ( void )

nodiscard

Tear down DOTF and release all hardware state.

Companion to ra8_dotf_open: disables both channels and gates the shared OSPI MSTP bits via ra8_dotf_deinit. Provided as a thin symmetric helper so callers do not have to mix open / deinit vocabulary.

Returns: ra8_err_t error code.

Precondition: All XiP traffic is quiesced.

Postcondition: Both DOTF channels disabled and gated.

Note: Thread safety: not thread-safe.

See also: ra8_dotf_open

Since: 0.1.0

Definition at line 221 of file ra8_dotf_power.c.

References ra8_dotf_deinit().

◆ ra8_dotf_enter_stop()

ra8_err_t ra8_dotf_enter_stop ( void )

nodiscard

Park the DOTF block prior to entering a low-power mode.

Returns: ra8_err_t error code.

Precondition: All XiP traffic from the matching xSPI is quiesced.

Postcondition: DOTF MSTP bits are set; AES core is gated.

Since: 0.1.0

Definition at line 253 of file ra8_dotf_power.c.

References k_ra8_dotf_channel_count, k_ra8_ok, ra8_mstp_disable(), and s_dotf_mstp_table.

◆ ra8_dotf_exit_stop()

ra8_err_t ra8_dotf_exit_stop ( void )

nodiscard

Bring the DOTF block back from low-power mode.

Returns: ra8_err_t error code.

Precondition: System clocks have been restored.

Postcondition: DOTF MSTP bits are cleared but channels remain disabled.

Since: 0.1.0

Definition at line 262 of file ra8_dotf_power.c.

References k_ra8_dotf_channel_count, k_ra8_ok, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, s_dotf_mstp_table, and s_tag.

◆ ra8_dotf_open()

ra8_err_t ra8_dotf_open ( const ra8_dotf_open_cfg_t * cfg )

nodiscard

One-shot DOTF bring-up: init + install_key + set_iv + set_region (+ enable).

Convenience entry point for the bootloader: drives ra8_dotf_init (idempotent re-init is allowed), ra8_dotf_install_key, ra8_dotf_set_iv, ra8_dotf_set_region, ra8_dotf_select_region, ra8_dotf_set_sca_level and (optionally) ra8_dotf_enable from a single descriptor. Used during cold boot when XiP code lives behind the AES core and must be armed before the first instruction fetch into the encrypted window.

Parameters

[in] cfg Non-NULL bring-up descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel armed (or staged + idle).
k_ra8_err_null_ptr	cfg was NULL.
k_ra8_err_invalid_arg	Channel out of range or descriptor bad.
k_ra8_err_hw_init_failed	MSTP enable failed.

Precondition: IRQs masked or single-threaded boot context.; cfg->key.valid != 0.

Postcondition: Channel cfg->channel is staged + (if enable_after) armed.; REG00 / REG03 / CONVAREAST / CONVAREAD reflect the descriptor.

Note: Thread safety: not thread-safe.

See also: ra8_dotf_close

Since: 0.1.0

Definition at line 206 of file ra8_dotf_power.c.

References internal_open_finalise(), internal_open_stage_key_iv_region(), internal_open_validate_init(), k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, and s_tag.

◆ ra8_dotf_set_region_window()

ra8_err_t ra8_dotf_set_region_window	(	uint8_t	channel,
		uint32_t	start,
		uint32_t	len )

nodiscard

Stage a region from a (start, length) pair instead of a struct.

Thin convenience wrapper around ra8_dotf_set_region for callers that have a base + len pair handy. Internally constructs a ra8_dotf_region_t with region_id = 0, key_index = 0 and forwards. The end address is derived as start + len - 1 and is subject to the same 4 KB alignment constraints as the struct API.

Parameters

[in]	channel	Channel index 0..1.
[in]	start	First byte of the encrypted region.
[in]	len	Length of the region in bytes (must be > 0 and 4 KB aligned).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Region staged in slot 0.
k_ra8_err_invalid_arg	Channel out of range or alignment bad.

Precondition: ra8_dotf_init (or ra8_dotf_open) has run.; len > 0 and (start | len) % 4096 == 0.

Postcondition: Slot 0 of the channel mirrors the constructed region.; Hardware CONVAREAST / CONVAREAD are NOT updated until ra8_dotf_select_region is called.

Note: Thread safety: not thread-safe.

See also: ra8_dotf_set_region

Since: 0.1.0

Definition at line 227 of file ra8_dotf_power.c.

References internal_ra8_dotf_internal_channel_in_range(), k_ra8_dotf_addr_low_mask, k_ra8_err_invalid_arg, and ra8_dotf_set_region().

Variable Documentation

◆ s_dotf_mstp_table

const ra8_mstp_t s_dotf_mstp_table[k_ra8_dotf_channel_count]

static

Initial value:

                                          = {
  k_ra8_mstp_ospi0,
  k_ra8_mstp_ospi1,
}

Channel-index -> MSTP id lookup.

DOTF0 + XSPI0 share MSTPB16; DOTF1 + XSPI1 share MSTPB17 (HUM Ch 11.2.7 MSTPCRB description references both peripherals). The MSTP wrapper enums in ra8_mstp_regs.h already encode this as k_ra8_mstp_ospi0 / k_ra8_mstp_ospi1 – the comments call them out as "OSPI0+DOTF0" / "OSPI1+DOTF1" so we just reuse them here rather than minting DOTF-specific aliases.

Definition at line 50 of file ra8_dotf_power.c.

◆ s_tag

const char* s_tag = "DOTF"

static

Logging tag for ra8_log_* calls.

Definition at line 36 of file ra8_dotf_power.c.

Functions

Variables

Detailed Description

Function Documentation

◆ internal_open_finalise()

◆ internal_open_stage_key_iv_region()

◆ internal_open_validate_init()

◆ ra8_dotf_close()

◆ ra8_dotf_enter_stop()

◆ ra8_dotf_exit_stop()

◆ ra8_dotf_open()

◆ ra8_dotf_set_region_window()

Variable Documentation

◆ s_dotf_mstp_table

◆ s_tag