ra8_dotf.h File Reference

Decryption On The Fly (DOTF) HAL driver public API. More...

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

Include dependency graph for ra8_dotf.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_dotf_region_t
	Conversion-area descriptor for ra8_dotf_set_region. More...
struct	ra8_dotf_key_handle_t
	Wrapped-key handle handed to DOTF by ra8_rsip. More...
struct	ra8_dotf_open_cfg_t
	One-shot DOTF bring-up descriptor consumed by ra8_dotf_open. More...

Typedefs
typedef void(*	ra8_dotf_event_fn_t) (void *ctx, uint8_t channel)
	DOTF fault / status event callback.

Enumerations
enum	ra8_dotf_key_size_t : uint32_t {   k_ra8_dotf_key_size_128 = k_ra8_dotf_reg00_key_size_128 ,   k_ra8_dotf_key_size_192 = k_ra8_dotf_reg00_key_size_192 ,   k_ra8_dotf_key_size_256 = k_ra8_dotf_reg00_key_size_256 }
	AES key sizes supported by the DOTF AES core. More...
enum	ra8_dotf_sca_level_t : uint8_t {   k_ra8_dotf_sca_off = 0U ,   k_ra8_dotf_sca_standard = 1U ,   k_ra8_dotf_sca_max = 2U }
	Side-channel countermeasure tuning levels. More...

Functions
ra8_err_t	ra8_dotf_init (void)
	Power on the DOTF block and reset both channels.
ra8_err_t	ra8_dotf_deinit (void)
	Disable DOTF and gate the OSPI clock.
ra8_err_t	ra8_dotf_set_region (uint8_t channel, const ra8_dotf_region_t *region)
	Stage one DOTF region in the channel's region table.
ra8_err_t	ra8_dotf_select_region (uint8_t channel, uint8_t region_id)
	Promote a staged region into the live CONVAREAST / CONVAREAD pair.
ra8_err_t	ra8_dotf_get_active_region (uint8_t channel, ra8_dotf_region_t *region)
	Read back the active region for a channel.
ra8_err_t	ra8_dotf_install_key (uint8_t channel, const ra8_dotf_key_handle_t *handle)
	Bind a wrapped AES key handle to a DOTF channel.
ra8_err_t	ra8_dotf_rotate_key (uint8_t channel, const ra8_dotf_key_handle_t *new_handle, const uint32_t *iv_words)
	Atomically rotate the key bound to a channel.
ra8_err_t	ra8_dotf_set_iv (uint8_t channel, const uint32_t *iv_words)
	Stage the AES counter-mode IV for a channel via REG03.
ra8_err_t	ra8_dotf_enable (uint8_t channel)
	Enable AES decryption for one channel.
ra8_err_t	ra8_dotf_disable (uint8_t channel)
	Disable AES decryption for one channel (transparent bypass).
ra8_err_t	ra8_dotf_set_sca_level (uint8_t channel, ra8_dotf_sca_level_t level)
	Update the side-channel countermeasure level for a channel.
ra8_err_t	ra8_dotf_set_key_size (uint8_t channel, ra8_dotf_key_size_t size)
	Update the cached AES key size for a channel.
ra8_err_t	ra8_dotf_run_self_test (uint8_t channel, uint32_t *out_status)
	Trigger the built-in self-test (REG00 bit 20) for a channel.
ra8_err_t	ra8_dotf_get_status (uint8_t channel, uint32_t *out_mask)
	Read REG00 (raw control / status snapshot).
ra8_err_t	ra8_dotf_clear_status (uint8_t channel)
	Clear REG00 (force the channel into bypass).
ra8_err_t	ra8_dotf_attach_handler (ra8_dotf_event_fn_t fn, void *ctx)
	Register a fault / event callback (shared across both channels).
void	ra8_dotf_dispatch (uint8_t channel)
	Dispatch a DOTF event from the IRQ glue.
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.

Detailed Description

Decryption On The Fly (DOTF) HAL driver public API.

Tag

[Ring 3 / HAL] {World: S}

Driver for the RA8D2 DOTF block (HUM Ch 45 p 3048..3050). DOTF transparently decrypts read traffic on the AXI side of the OSPI / xSPI controller using an AES core configured in CTR mode, allowing encrypted code stored in external flash to execute in place from the XiP window.

The driver covers every register documented in HUM Ch 45 plus the REG00 sub-fields cross-referenced from the FSP r_ospi_b driver (key size, AES mode, side-channel countermeasure, self-test trigger, IV staging via REG03). It also implements:

• Multi-region staging per channel: software keeps up to k_ra8_dotf_max_regions pre-validated regions, only one of which can be live at a time per HUM 45.3 ("one contiguous area"); the active region is selected via ra8_dotf_select_region for live key-region rotation.
• Live key rotation: ra8_dotf_rotate_key quiesces the channel, re-stages the wrapped key handle from ra8_rsip, and re-arms the AES core in a single bounded sequence.
• RSIP-key-injection wiring: ra8_dotf_install_key consumes a ra8_dotf_key_handle_t (an opaque cookie produced by ra8_rsip's key-injection layer) and stages the wrapped-key bytes into REG03 in big-endian order. The HAL never touches raw key material – it only forwards the handle to RSIP.
• Region overlap validation: ra8_dotf_set_region rejects any region that overlaps another channel's currently-armed region (HUM Ch 5 + Ch 45.3 implicitly require disjoint conversion areas because both channels share the same AXI bus and a single AES key cannot decrypt both halves correctly).
• Both OSPI-channel pairings: DOTF0+XSPI0 (window 0x8000_0000..0x9FFF_FFFF) and DOTF1+XSPI1 (window 0x7000_0000..0x7FFF_FFFF) are first-class peers; every public API takes a channel argument and validates it.
• Side-channel countermeasure tuning: REG00 bits 16/17 are exposed via ra8_dotf_set_sca_level.
• Self-test trigger: REG00 bit 20 is exposed via ra8_dotf_run_self_test; the result is observable through ra8_dotf_get_status.
• Lifecycle (init / deinit / enter_stop / exit_stop), per-channel enable / disable, dispatch glue.

Warning

Misconfiguration of DOTF when executing from the encrypted XSPI window will cause the CPU to fetch garbage and almost certainly take a HardFault. The driver MUST be initialized and the conversion region MUST be programmed before control jumps into XiP code that lives in the encrypted area. The intended call order on a cold boot is: ra8_dotf_init() -> ra8_dotf_install_key(handle) -> ra8_dotf_set_iv(iv) -> ra8_dotf_set_region(region) -> ra8_dotf_enable() -> jump into XiP code.

DOTF0 and DOTF1 share their MSTP bits with XSPI0 / XSPI1 respectively (HUM Ch 11.2.7 MSTPCRB bits 16/17 cover the OSPI+DOTF pair). Tearing down DOTF therefore also tears down the matching xSPI controller – callers running XiP must keep DOTF up for the lifetime of the XiP region.

State Machine

Copyright

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

Definition in file ra8_dotf.h.

Typedef Documentation

ra8_dotf_event_fn_t

typedef void(* ra8_dotf_event_fn_t) (void *ctx, uint8_t channel)

DOTF fault / status event callback.

Parameters

[in]	ctx	Caller context.
[in]	channel	Channel index 0..1 that raised the event.

Definition at line 214 of file ra8_dotf.h.

Enumeration Type Documentation

ra8_dotf_key_size_t

enum ra8_dotf_key_size_t : uint32_t

AES key sizes supported by the DOTF AES core.

HUM Ch 45.1 p 3048 ("AES core function: Block size 128-bit; Key size: 128-bit, 192-bit, 256-bit"). The encoded values are the raw REG00 patterns that select each size; the driver simply ORs them into the assembled REG00 word.

Enumerator
k_ra8_dotf_key_size_128	128-bit AES.
k_ra8_dotf_key_size_192	192-bit AES.
k_ra8_dotf_key_size_256	256-bit AES.

Definition at line 128 of file ra8_dotf.h.

ra8_dotf_sca_level_t

enum ra8_dotf_sca_level_t : uint8_t

Side-channel countermeasure tuning levels.

HUM Ch 45.1 p 3048 ("Tamper Resistance: Countermeasures available for side-channel attacks, including SPA/DPA and timing attacks"). The HUM does not expose the raw bit names; the driver maps three coarse levels onto REG00 bits 17:16 per the FSP reference:

• off: bit16=0, bit17=0 (no SCA – not recommended)
• standard: bit16=1, bit17=0 (default after ra8_dotf_init)
• max: bit16=1, bit17=1 (paranoid – higher latency)

Enumerator
k_ra8_dotf_sca_off	Side-channel countermeasures disabled.
k_ra8_dotf_sca_standard	Default level, bit 16 set.
k_ra8_dotf_sca_max	Maximum level, bits 16 + 17 set.

Definition at line 148 of file ra8_dotf.h.

Function Documentation

ra8_dotf_attach_handler()

ra8_err_t ra8_dotf_attach_handler ( ra8_dotf_event_fn_t fn, void * ctx )

nodiscard

Register a fault / event callback (shared across both channels).

DOTF on its own does not raise an IRQ – faults surface through the matching xSPI controller's INTS register. The platform IRQ glue forwards the channel index to ra8_dotf_dispatch which fires this callback. Useful for telemetry on key-mismatch / illegal-region hits during bring-up.

Parameters

[in]	fn	Callback fired on dispatch.
[in]	ctx	Context forwarded to the callback.

Returns

ra8_err_t error code.

Precondition

Called with IRQs masked or before dispatch ever fires.

Postcondition

Subsequent dispatches will fire fn(ctx, channel).

Since

0.1.0

Definition at line 948 of file ra8_dotf.c.

References k_ra8_ok, s_dotf_ctx, and s_dotf_fn.

ra8_dotf_clear_status()

ra8_err_t ra8_dotf_clear_status ( uint8_t channel )

nodiscard

Clear REG00 (force the channel into bypass).

Parameters

[in]

channel

Channel index 0..1.

Returns

ra8_err_t error code.

Precondition

channel is in range.

Postcondition

REG00 reads 0.

Since

0.1.0

Definition at line 928 of file ra8_dotf.c.

References internal_channel_in_range(), k_ra8_dotf_reg00_disable_value, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dotf_regs(), ra8_dotf_regs_t::REG00, s_dotf_state, and s_tag.

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

ra8_err_t ra8_dotf_deinit ( void )

nodiscard

Disable DOTF and gate the OSPI clock.

Returns

ra8_err_t error code.

Precondition

IRQs masked or single-threaded teardown context.

Postcondition

Both DOTF channels are disabled and MSTPB16/17 are set.

Warning

Will also gate the matching XSPI controller – callers must have stopped all XiP traffic first.

Since

0.1.0

Definition at line 545 of file ra8_dotf.c.

References internal_state_reset(), k_ra8_dotf_channel_count, k_ra8_dotf_reg00_disable_value, k_ra8_ok, ra8_dotf_regs(), ra8_mstp_disable(), ra8_dotf_regs_t::REG00, s_dotf_ctx, s_dotf_fn, and s_dotf_mstp_table.

Referenced by ra8_dotf_close().

ra8_dotf_disable()

ra8_err_t ra8_dotf_disable ( uint8_t channel )

nodiscard

Disable AES decryption for one channel (transparent bypass).

Parameters

[in]

channel

Channel index 0..1.

Returns

ra8_err_t error code.

Precondition

ra8_dotf_init has run.

Postcondition

REG00 reads 0 and the conversion area passes through.

Since

0.1.0

Definition at line 823 of file ra8_dotf.c.

References internal_channel_in_range(), k_ra8_dotf_reg00_disable_value, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dotf_regs(), ra8_dotf_regs_t::REG00, s_dotf_state, and s_tag.

ra8_dotf_dispatch()

void ra8_dotf_dispatch

(

uint8_t

channel

)

Dispatch a DOTF event from the IRQ glue.

Parameters

[in]

channel

Channel index 0..1 that raised the event. Out of range channels are dropped silently.

Since

0.1.0

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.

Definition at line 956 of file ra8_dotf.c.

References internal_channel_in_range(), s_dotf_ctx, and s_dotf_fn.

ra8_dotf_enable()

ra8_err_t ra8_dotf_enable ( uint8_t channel )

nodiscard

Enable AES decryption for one channel.

Writes the cached REG00 word (default 0x2200_0000 ORed with the bound key-size bits, the SCA bits, and the enable bit). The channel must have a key staged and a region selected.

Parameters

[in]

channel

Channel index 0..1.

Returns

ra8_err_t error code.

Precondition

ra8_dotf_set_region + ra8_dotf_select_region have been called for channel.

ra8_dotf_install_key has been called for channel.

Postcondition

REG00 reflects the assembled key-size + SCA + enable pattern.

Subsequent reads in the conversion area go through the AES core.

Warning

If the conversion region overlaps live XiP code the CPU will fault on the next instruction fetch. Callers must ensure no fetches target the encrypted window until the key is in place.

Since

0.1.0

Definition at line 804 of file ra8_dotf.c.

References ra8_dotf_chan_state_t::enabled, internal_assemble_reg00(), internal_channel_in_range(), k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dotf_regs(), ra8_log_info_val, ra8_dotf_regs_t::REG00, s_dotf_state, and s_tag.

Referenced by internal_open_finalise().

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

ra8_err_t ra8_dotf_get_active_region ( uint8_t channel, ra8_dotf_region_t * region )

nodiscard

Read back the active region for a channel.

Parameters

[in]	channel	Channel index 0..1.
[out]	region	Receives a copy of the active descriptor.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Descriptor returned.
k_ra8_err_null_ptr	region is NULL.
k_ra8_err_invalid_arg	Channel out of range.
k_ra8_err_invalid_state	No region active on channel.

Precondition

region is non-NULL.

channel is in range.

Postcondition

On success *region holds the live region descriptor.

Hardware state is unchanged.

Since

0.1.0

Definition at line 618 of file ra8_dotf.c.

References ra8_dotf_chan_state_t::active_region_id, internal_channel_in_range(), k_ra8_dotf_no_region, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dotf_chan_state_t::regions, s_dotf_state, and s_tag.

ra8_dotf_get_status()

ra8_err_t ra8_dotf_get_status ( uint8_t channel, uint32_t * out_mask )

nodiscard

Read REG00 (raw control / status snapshot).

Parameters

[in]	channel	Channel index 0..1.
[out]	out_mask	Receives REG00 contents.

Returns

ra8_err_t error code.

Precondition

out_mask is non-NULL.

channel is in range.

Postcondition

On success, *out_mask reflects the live REG00 value.

Since

0.1.0

Definition at line 913 of file ra8_dotf.c.

References internal_channel_in_range(), k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dotf_regs(), ra8_dotf_regs_t::REG00, and s_tag.

Referenced by internal_dotf_demo_sample().

ra8_dotf_init()

ra8_err_t ra8_dotf_init ( void )

nodiscard

Power on the DOTF block and reset both channels.

Clears MSTPB16 (DOTF0 + XSPI0) and MSTPB17 (DOTF1 + XSPI1) via ra8_mstp_enable, then writes 0 to each channel's REG00 and clears CONVAREAST / CONVAREAD to their reset values. Also scrubs every staged region slot, the IV cache, and the bound key handles.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	DOTF clocked and zeroed.
k_ra8_err_hw_init_failed	MSTP enable failed for either id.

Precondition

IRQs masked or single-threaded init context.

ra8_mstp_init has been called.

Postcondition

Both DOTF channels are reachable but disabled.

REG00 of every channel reads 0.

Note

Thread safety: not thread-safe.

See also

ra8_dotf_set_region

ra8_dotf_enable

Since

0.1.0

Definition at line 524 of file ra8_dotf.c.

References internal_channel_reset(), internal_state_reset(), k_ra8_dotf_channel_count, k_ra8_err_hw_init_failed, k_ra8_ok, ra8_dotf_regs(), ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, s_dotf_ctx, s_dotf_fn, s_dotf_mstp_table, and s_tag.

Referenced by internal_open_validate_init(), and main().

ra8_dotf_install_key()

ra8_err_t ra8_dotf_install_key ( uint8_t channel, const ra8_dotf_key_handle_t * handle )

nodiscard

Bind a wrapped AES key handle to a DOTF channel.

Copies the handle into the driver's per-channel slot and stages the wrapped-key payload into REG03 in big-endian word order. The channel is left disabled; the AES core only goes hot once ra8_dotf_enable (or ra8_dotf_rotate_key) is called. The HAL does not unwrap the key – that work belongs to ra8_rsip and runs before this call. The handle's size field is mirrored into the driver's REG00 cache so subsequent ra8_dotf_enable writes the correct key-size bits.

Parameters

[in]	channel	Channel index 0..1.
[in]	handle	Non-NULL handle. handle->valid must be non-0.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Key staged.
k_ra8_err_null_ptr	handle is NULL.
k_ra8_err_invalid_arg	Channel out of range or handle invalid.

Precondition

handle is non-NULL and handle->valid != 0.

ra8_dotf_init has run.

Postcondition

The channel's bound key handle equals *handle.

REG03 has been written words_for_size(handle->size) times.

Warning

Do NOT call this while the channel is enabled. Re-keying a live channel must go through ra8_dotf_rotate_key.

Since

0.1.0

Definition at line 637 of file ra8_dotf.c.

References ra8_dotf_chan_state_t::cached_key_size, internal_channel_in_range(), internal_stage_key(), k_ra8_dotf_key_size_128, k_ra8_dotf_key_size_192, k_ra8_dotf_key_size_256, k_ra8_err_invalid_arg, k_ra8_ok, ra8_dotf_chan_state_t::key, RA8_CHECK_NULL_PTR, ra8_dotf_regs(), ra8_log_info_val, s_dotf_state, s_tag, ra8_dotf_key_handle_t::size, and ra8_dotf_key_handle_t::valid.

Referenced by internal_open_stage_key_iv_region().

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

ra8_err_t ra8_dotf_rotate_key ( uint8_t channel, const ra8_dotf_key_handle_t * new_handle, const uint32_t * iv_words )

nodiscard

Atomically rotate the key bound to a channel.

Quiesces the channel (writes 0 to REG00), re-stages the new wrapped key + IV, then re-arms the AES core with the cached key- size and SCA settings. Used by the bootloader to swap signing keys during anti-rollback handling.

Sequence:

1. Save current REG00 enable state.
2. Write 0 to REG00 (disable AES).
3. Replace the bound key handle.
4. Re-stage the IV via REG03.
5. Re-arm REG00 with the new key-size + SCA + enable bits.

Parameters

[in]	channel	Channel index 0..1.
[in]	new_handle	Non-NULL replacement key.
[in]	iv_words	k_ra8_dotf_iv_word_count words of new IV (or NULL to reuse the current IV).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Rotation complete.
k_ra8_err_null_ptr	new_handle is NULL.
k_ra8_err_invalid_arg	Channel out of range or handle invalid.
k_ra8_err_invalid_state	No region active on the channel.

Precondition

ra8_dotf_install_key was called at least once.

A region is currently armed (select_region ran).

Postcondition

The new key is in REG03, REG00 is re-armed with enable bit.

The active key handle reflects *new_handle.

Warning

Outstanding XiP fetches between step 2 and step 5 will observe garbage. Callers must temporarily steer instruction fetches away from the encrypted window (typically by jumping into SRAM) before invoking this.

Since

0.1.0

Definition at line 764 of file ra8_dotf.c.

References ra8_dotf_chan_state_t::cached_key_size, ra8_dotf_chan_state_t::enabled, internal_assemble_reg00(), internal_rotate_iv(), internal_stage_key(), internal_validate_rotate_inputs(), k_ra8_dotf_reg00_disable_value, k_ra8_ok, ra8_dotf_chan_state_t::key, RA8_CHECK_NULL_PTR, ra8_dotf_regs(), ra8_log_info_val, RA8_RETURN_ON_ERROR, ra8_dotf_regs_t::REG00, s_dotf_state, s_tag, and ra8_dotf_key_handle_t::size.

ra8_dotf_run_self_test()

ra8_err_t ra8_dotf_run_self_test ( uint8_t channel, uint32_t * out_status )

nodiscard

Trigger the built-in self-test (REG00 bit 20) for a channel.

HUM Ch 45.1 p 3048 ("Supports self-test function"). Sets bit 20 of REG00, polls for completion by re-reading REG00 a bounded number of times, and returns the post-test snapshot via out_status. The bit auto-clears in real hardware; in the fake the bit remains set after the spin (the host has no way to model AES timing) – callers MUST treat out_status as opaque diagnostic data, not a pass/fail indicator on the host.

Parameters

[in]	channel	Channel index 0..1.
[out]	out_status	Non-NULL diagnostic snapshot.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Self-test triggered.
k_ra8_err_null_ptr	out_status is NULL.
k_ra8_err_invalid_arg	Channel out of range.
k_ra8_err_hw_timeout	SELF_TEST did not clear within the bounded wait.

Precondition

ra8_dotf_init has run.

Channel is currently disabled.

Postcondition

REG00 bit 20 was set at least once.

On return, REG00 has been restored to its pre-test value.

Since

0.1.0

Definition at line 883 of file ra8_dotf.c.

References internal_channel_in_range(), k_ra8_dotf_reg00_self_test, k_ra8_dotf_self_test_spin, k_ra8_err_invalid_arg, RA8_CHECK_NULL_PTR, ra8_dotf_regs(), ra8_hw_wait_flag_clear32(), ra8_dotf_regs_t::REG00, and s_tag.

Referenced by internal_dotf_demo_sample().

ra8_dotf_select_region()

ra8_err_t ra8_dotf_select_region ( uint8_t channel, uint8_t region_id )

nodiscard

Promote a staged region into the live CONVAREAST / CONVAREAD pair.

Atomically writes CONVAREAD then CONVAREAST (in that order per the FSP reference comment "Set the end and start area for DOTF conversion in that order to ensure that end address is always higher than start address.", r_ospi_b.c). Caller is expected to have called ra8_dotf_disable first; the function does NOT clear REG00 itself so the AES core stays primed for the subsequent ra8_dotf_enable call.

Parameters

[in]	channel	Channel index 0..1.
[in]	region_id	Slot index in the channel's region table.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Region promoted.
k_ra8_err_invalid_arg	Out-of-range channel or region_id.
k_ra8_err_invalid_state	The slot has not been staged.

Precondition

ra8_dotf_set_region(channel, ..., region_id=region_id) previously returned k_ra8_ok.

Channel is currently disabled (HUM 45.3.1 p 3049).

Postcondition

CONVAREAST / CONVAREAD reflect the staged region.

The "active region" cache for channel is updated.

Since

0.1.0

Definition at line 591 of file ra8_dotf.c.

References ra8_dotf_chan_state_t::active_region_id, ra8_dotf_regs_t::CONVAREAD, ra8_dotf_regs_t::CONVAREAST, ra8_dotf_region_t::end_addr, internal_channel_in_range(), k_ra8_dotf_addr_mask, k_ra8_dotf_max_regions, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dotf_regs(), ra8_dotf_chan_state_t::region_valid, ra8_dotf_chan_state_t::regions, s_dotf_state, s_tag, and ra8_dotf_region_t::start_addr.

Referenced by internal_open_stage_key_iv_region().

ra8_dotf_set_iv()

ra8_err_t ra8_dotf_set_iv ( uint8_t channel, const uint32_t * iv_words )

nodiscard

Stage the AES counter-mode IV for a channel via REG03.

Per HUM Ch 45.1 p 3048 the AES counter is {IV[127:28], Address[31:4]}. Software still loads a full 128-bit IV; the hardware silently overwrites the bottom 28 bits with the AXI address bits at decryption time. The four 32-bit words are written into REG03 in big-endian byte order, mirroring the FSP reference (r_ospi_b.c).

Parameters

[in]	channel	Channel index 0..1.
[in]	iv_words	Pointer to k_ra8_dotf_iv_word_count words.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Words written.
k_ra8_err_null_ptr	iv_words is NULL.
k_ra8_err_invalid_arg	Channel out of range.

Precondition

iv_words is non-NULL and points to >= 4 valid words.

Channel is currently disabled.

Postcondition

The IV cache for channel mirrors the new value.

REG03 has been written 4 times in big-endian word order.

Since

0.1.0

Definition at line 661 of file ra8_dotf.c.

References internal_channel_in_range(), internal_stage_iv(), ra8_dotf_chan_state_t::iv_cache, ra8_dotf_chan_state_t::iv_valid, k_ra8_dotf_iv_word_count, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dotf_regs(), s_dotf_state, and s_tag.

Referenced by internal_open_stage_key_iv_region().

ra8_dotf_set_key_size()

ra8_err_t ra8_dotf_set_key_size ( uint8_t channel, ra8_dotf_key_size_t size )

nodiscard

Update the cached AES key size for a channel.

Parameters

[in]	channel	Channel index 0..1.
[in]	size	k_ra8_dotf_key_size_*.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Size cached; if armed, REG00 updated.
k_ra8_err_invalid_arg	Channel out of range or unknown size.

Precondition

ra8_dotf_init has run.

Postcondition

REG00 key-size bits reflect size (only if armed).

Subsequent ra8_dotf_enable calls write the new size.

Since

0.1.0

Definition at line 863 of file ra8_dotf.c.

References ra8_dotf_chan_state_t::cached_key_size, ra8_dotf_chan_state_t::enabled, internal_assemble_reg00(), internal_channel_in_range(), k_ra8_dotf_key_size_128, k_ra8_dotf_key_size_192, k_ra8_dotf_key_size_256, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dotf_regs(), ra8_dotf_regs_t::REG00, s_dotf_state, and s_tag.

ra8_dotf_set_region()

ra8_err_t ra8_dotf_set_region ( uint8_t channel, const ra8_dotf_region_t * region )

nodiscard

Stage one DOTF region in the channel's region table.

Validates 4 KB alignment, start <= end, that the region falls entirely inside the matching channel's XSPI window ([0x8000_0000..0x9FFF_FFFF] for DOTF0, [0x7000_0000.. 0x7FFF_FFFF] for DOTF1), and that the region does NOT overlap the other channel's currently-armed region. On success the descriptor is copied into slot region->region_id of the channel's staging table; the slot becomes "live" only when ra8_dotf_select_region(channel, region_id) is called.

Parameters

[in]	channel	Channel index 0..1.
[in]	region	Non-NULL region descriptor.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Region staged.
k_ra8_err_null_ptr	region is NULL.
k_ra8_err_invalid_arg	channel or region_id out of range, addresses not 4 KB aligned, start > end, or region escapes the matching XSPI window.
k_ra8_err_conflict	Region overlaps the other channel's currently-armed region.

Precondition

ra8_dotf_init has run.

Channel channel may be enabled or disabled (the slot table is software-only until select_region is called).

Postcondition

Slot region->region_id of channel channel mirrors *region and is marked valid.

The hardware CONVAREAST / CONVAREAD registers are NOT updated until ra8_dotf_select_region runs.

Warning

HUM 45.3.1 / 45.3.2 say: "Set before the AXI transfer request and do not make any further changes." Any change to the live region MUST go through ra8_dotf_disable -> ra8_dotf_select_region -> ra8_dotf_enable.

Since

0.1.0

Definition at line 569 of file ra8_dotf.c.

References internal_channel_in_range(), internal_check_overlap(), internal_validate_region(), k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_info_val, ra8_log_warn_val, ra8_dotf_region_t::region_id, ra8_dotf_chan_state_t::region_valid, ra8_dotf_chan_state_t::regions, s_dotf_state, and s_tag.

Referenced by internal_open_stage_key_iv_region(), and ra8_dotf_set_region_window().

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

ra8_dotf_set_sca_level()

ra8_err_t ra8_dotf_set_sca_level ( uint8_t channel, ra8_dotf_sca_level_t level )

nodiscard

Update the side-channel countermeasure level for a channel.

Parameters

[in]	channel	Channel index 0..1.
[in]	level	k_ra8_dotf_sca_off / standard / max.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Cached and (if armed) written through.
k_ra8_err_invalid_arg	Channel out of range or unknown level.

Precondition

ra8_dotf_init has run.

Postcondition

REG00 SCA bits reflect level; if the channel was already enabled, the AES core is updated in place (single REG00 write).

Since

0.1.0

Definition at line 843 of file ra8_dotf.c.

References ra8_dotf_chan_state_t::cached_sca, ra8_dotf_chan_state_t::enabled, internal_assemble_reg00(), internal_channel_in_range(), k_ra8_dotf_sca_max, k_ra8_dotf_sca_off, k_ra8_dotf_sca_standard, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dotf_regs(), ra8_dotf_regs_t::REG00, s_dotf_state, and s_tag.

Referenced by internal_open_finalise().