Shared aliased-memory backing and Unicorn memory-map bindings. More...

#include <stddef.h>
#include <stdint.h>
#include <unicorn/unicorn.h>
#include "emu_memory_access.h"
#include "ra8_attributes.h"

Include dependency graph for emu_memmap.h:

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

Go to the source code of this file.

Data Structures
struct	mem_region_t
	One emulated memory-region table row. More...
struct	emu_memmap_result_t
	Exact requirements and operation outcome. More...
struct	emu_memmap_backing_t
	One owned host aperture mapping. More...
struct	emu_memmap_binding_t
	One caller-owned association between a Unicorn engine and backing. More...
struct	emu_memmap_workspace
	Independent aperture backing with at most two engine bindings. More...

Typedefs
typedef struct emu_memmap_workspace	emu_memmap_workspace_t
	Independent aperture backing with at most two engine bindings.

Enumerations
enum	ram_region_t : uint32_t { k_dtcm_base = 0x20000000U , k_dtcm_end = 0x20010000U , k_sram_base = 0x22000000U , k_sram_end = 0x22100000U , k_sdram_base = 0x68000000U , k_sdram_end = 0x6C000000U , k_ns_sdram_base = 0x78000000U , k_page_size = 0x1000U }
	Address constants shared with framebuffer and alias validation. More...
enum	emu_memmap_limit_t : size_t { k_emu_memmap_backing_count = 3U , k_emu_memmap_binding_count = 2U }
	Fixed backing and binding limits. More...
enum	emu_memmap_status_t : uint8_t { k_emu_memmap_ok = 0U , k_emu_memmap_invalid , k_emu_memmap_backing , k_emu_memmap_unicorn }
	Semantic result for backing lifecycle operations. More...

Functions
emu_memmap_result_t	emu_memmap_requirements (void)
	Report the immutable aliased-aperture backing geometry.
emu_memmap_result_t	emu_memmap_open (emu_memmap_workspace_t *workspace)
	Create three independent, lazily-committed host aperture mappings.
emu_memmap_result_t	emu_memmap_attach (emu_memmap_workspace_t workspace, uc_engine uc)
	Map one Unicorn engine onto the shared aperture backing.
bool	emu_memmap_detach (emu_memmap_workspace_t workspace, uc_engine uc)
	Remove one engine binding before closing that Unicorn engine.
bool	emu_memmap_close (emu_memmap_workspace_t *workspace)
	Release every host aperture mapping after all engines detached.
const mem_region_t *	emu_memmap_regions (uint32_t *count)
	Return the static emulated memory-region table.
uint64_t	emu_memmap_mram_base (void)
	Return the MRAM boot-vector base.

Detailed Description

Shared aliased-memory backing and Unicorn memory-map bindings.

Owns three page-aligned, lazily-committed host mappings for the aliased SRAM, SDRAM and OSPI apertures. Every attached Unicorn engine binds each aperture AND its TrustZone bit[28] alias onto those same host pages, so the Secure view, the Non-secure view and the second CPU engine are one state by construction rather than by a per-store reconciliation protocol.

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

Since: 0.1.0

Definition in file emu_memmap.h.

Typedef Documentation

◆ emu_memmap_workspace_t

typedef struct emu_memmap_workspace emu_memmap_workspace_t

Independent aperture backing with at most two engine bindings.

Enumeration Type Documentation

◆ emu_memmap_limit_t

enum emu_memmap_limit_t : size_t

Fixed backing and binding limits.

Enumerator
k_emu_memmap_backing_count	SRAM, SDRAM, and OSPI host mappings.
k_emu_memmap_binding_count	CPU0 and optional CPU1 engines.

Definition at line 56 of file emu_memmap.h.

◆ emu_memmap_status_t

enum emu_memmap_status_t : uint8_t

Semantic result for backing lifecycle operations.

Enumerator
k_emu_memmap_ok	Operation completed exactly.
k_emu_memmap_invalid	Pointer, state, or engine was invalid.
k_emu_memmap_backing	A host aperture mapping could not be made.
k_emu_memmap_unicorn	Unicorn map or window install failed.

Definition at line 62 of file emu_memmap.h.

◆ ram_region_t

enum ram_region_t : uint32_t

Address constants shared with framebuffer and alias validation.

Enumerator
k_dtcm_base	Data TCM start.
k_dtcm_end	Data TCM end.
k_sram_base	On-chip SRAM start.
k_sram_end	CPU0 SRAM end used by framebuffer checks.
k_sdram_base	External SDRAM start.
k_sdram_end	External SDRAM end.
k_ns_sdram_base	Non-secure SDRAM alias.
k_page_size	Unicorn and host mapping granule.

Definition at line 36 of file emu_memmap.h.

Function Documentation

◆ emu_memmap_attach()

emu_memmap_result_t emu_memmap_attach	(	emu_memmap_workspace_t *	workspace,
		uc_engine *	uc )

nodiscard

Map one Unicorn engine onto the shared aperture backing.

Maps every RA8D2 region into uc. The six aliased windows – the SRAM/SRAM2, SDRAM and OSPI Secure views and their IDAU bit[28] Non-secure aliases – are bound with uc_mem_map_ptr onto the workspace's host pages, so a store through any of them is immediately visible through every other one and in every other engine bound to the same workspace, at no per-store cost. Every other region is an ordinary private Unicorn mapping.

Parameters

[in,out]	workspace	Open aperture backing.
[in,out]	uc	Fresh Unicorn engine.

Returns: Lifecycle result with the aperture geometry.

Return values

k_emu_memmap_ok	The engine is mapped and the binding recorded.
k_emu_memmap_invalid	A null or unopened argument was supplied.
k_emu_memmap_unicorn	A region map or the MMIO window install failed.

Precondition: uc has no guest memory mappings.; workspace is open and has a free binding slot.

Postcondition: Success makes the shared apertures coherent with every bound engine.; Success records a binding that emu_memmap_close refuses to outlive.

Note: The caller still owns uc and must detach before closing it.

Since: 0.1.0

Definition at line 463 of file emu_memmap.c.

References emu_memmap_binding_t::active, emu_memmap_workspace::bindings, internal_map_periph_mmio(), internal_map_regions(), internal_result(), internal_seed_tsn(), k_emu_memmap_binding_count, k_emu_memmap_invalid, k_emu_memmap_ok, k_emu_memmap_unicorn, and emu_memmap_workspace::open.

Referenced by internal_cpu1_engine_init(), and internal_main_open_engine().

◆ emu_memmap_close()

bool emu_memmap_close ( emu_memmap_workspace_t * workspace )

Release every host aperture mapping after all engines detached.

Refuses while any binding is active, because a bound engine holds uc_mem_map_ptr references into the very pages this call unmaps.

Parameters

[in,out] workspace Open or already-closed caller workspace.

Returns: True when closed or already closed; false while a binding is live.

Return values

true	Every aperture mapping was released, or none was owned.
false	A binding is still active and nothing was released.

Precondition: workspace is non-null.; Every engine attached to workspace was detached first.

Postcondition: Success clears every backing pointer and the open flag.; Failure preserves the workspace so its engines can be detached.

Note: Calling this while an engine is still bound would strand that engine on unmapped host memory, so the refusal is load-bearing, not defensive.

Since: 0.1.0

Definition at line 500 of file emu_memmap.c.

References emu_memmap_binding_t::active, emu_memmap_workspace::bindings, internal_backings_close(), k_emu_memmap_binding_count, and emu_memmap_workspace::open.

Referenced by internal_main_load_images(), main(), and priv_run_cleanup().

◆ emu_memmap_detach()

bool emu_memmap_detach	(	emu_memmap_workspace_t *	workspace,
		uc_engine *	uc )

Remove one engine binding before closing that Unicorn engine.

Releases the binding slot uc occupies. The engine keeps its mappings until the caller closes it, so detach must happen before emu_memmap_close unmaps the host pages those mappings point at.

Parameters

[in,out]	workspace	Open backing containing the binding.
[in,out]	uc	Live bound engine.

Returns: Whether exactly one active binding was removed.

Return values

true	The binding for `uc` was found and released.
false	A null argument, or `uc` was not bound.

Precondition: workspace and uc are non-null.; The call executes on the emulator's single owning thread.

Postcondition: Success frees the binding slot for a later attach.; Ownership of caller-supplied storage is unchanged.

Note: The caller still owns and must close uc.

Since: 0.1.0

Definition at line 486 of file emu_memmap.c.

References emu_memmap_binding_t::active, emu_memmap_workspace::bindings, k_emu_memmap_binding_count, and emu_memmap_binding_t::uc.

Referenced by emu_cpu1_close(), internal_cpu1_engine_init(), internal_main_load_images(), and priv_run_cleanup().

◆ emu_memmap_mram_base()

uint64_t emu_memmap_mram_base ( void )

Return the MRAM boot-vector base.

The reset vector and the vector table live at the base of the MRAM code region; the run loop and exception model resolve VTOR from here.

Returns: Immutable MRAM base address.

Return values

value The MRAM region base recorded in the region table.

Precondition: No precondition: the value is a compile-time constant.; The call executes on the emulator's single owning thread.

Postcondition: No memory-map or engine state changes.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Return the MRAM boot-vector base.

Definition at line 523 of file emu_memmap.c.

References s_regions.

Referenced by internal_main_reset_vector(), internal_main_run_loaded(), internal_on_intr(), and warm_reboot().

◆ emu_memmap_open()

emu_memmap_result_t emu_memmap_open ( emu_memmap_workspace_t * workspace )

nodiscard

Create three independent, lazily-committed host aperture mappings.

Acquires one page-aligned zero-filled host mapping per shared aperture (SRAM, SDRAM, OSPI). The mappings are anonymous, so the 130 MiB of logical guest memory costs resident memory only for the pages the firmware actually touches. Distinct workspaces own distinct mappings and never share bytes.

Parameters

[out] workspace Receives the owned mappings on success.

Returns: Exact geometry and completion status.

Return values

k_emu_memmap_ok	Every aperture mapping was acquired.
k_emu_memmap_invalid	`workspace` was null or already open.
k_emu_memmap_backing	A host mapping failed; `os_error` holds errno.

Precondition: workspace is non-null.; workspace is not already open; re-opening one is rejected rather than leaking the apertures it already owns.

Postcondition: Success leaves every aperture zero-filled and no page resident.; Failure acquires nothing and leaves workspace untouched.

Note: Distinct workspaces own independent mappings and state.

Since: 0.1.0

Definition at line 439 of file emu_memmap.c.

References emu_memmap_workspace::backings, internal_backing_open(), internal_backings_close(), internal_result(), k_backing_ospi, k_backing_sdram, k_backing_sram, k_emu_memmap_backing, k_emu_memmap_backing_count, k_emu_memmap_invalid, k_emu_memmap_ok, k_ospi_size, k_sdram_size, k_sram_size, and emu_memmap_workspace::open.

Referenced by internal_main_open_memory().

◆ emu_memmap_regions()

const mem_region_t * emu_memmap_regions ( uint32_t * count )

Return the static emulated memory-region table.

Exposes the immutable RA8D2 region table so other engine code (framebuffer scanning, the cpu1 bring-up) can reason about the same map the attach path installs.

Parameters

[out] count Receives the immutable table row count.

Returns: Process-lifetime immutable region table.

Return values

nullptr Never returned; the table has static storage duration.

Precondition: count is non-null.; The call executes on the emulator's single owning thread.

Postcondition: No memory-map or engine state changes.; count holds the exact row count.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Return the static emulated memory-region table.

Definition at line 516 of file emu_memmap.c.

References s_regions.

◆ emu_memmap_requirements()

emu_memmap_result_t emu_memmap_requirements ( void )

nodiscard

Report the immutable aliased-aperture backing geometry.

Names the exact number of logical guest bytes the three shared apertures span, before any workspace or engine exists, so a caller can report the emulated memory footprint without opening anything.

Returns: Successful immutable requirement values.

Return values

value A result whose status is always k_emu_memmap_ok.

Precondition: No precondition: the reported geometry is a compile-time constant.; The call executes on the emulator's single owning thread.

Postcondition: Reports 136134656 logical aperture bytes.; No workspace, mapping, or engine state changes.

Note: Pure and safe to call before any engine or workspace exists.

Since: 0.1.0

Definition at line 434 of file emu_memmap.c.

References internal_result(), and k_emu_memmap_ok.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ emu_memmap_workspace_t

Enumeration Type Documentation

◆ emu_memmap_limit_t

◆ emu_memmap_status_t

◆ ram_region_t

Function Documentation

◆ emu_memmap_attach()

◆ emu_memmap_close()

◆ emu_memmap_detach()

◆ emu_memmap_mram_base()

◆ emu_memmap_open()

◆ emu_memmap_regions()

◆ emu_memmap_requirements()