emu_console.h File Reference

Emulator text-console surfaces: UART echo, ITM/SWO echo, escapes. More...

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

Include dependency graph for emu_console.h:

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

Go to the source code of this file.

Enumerations
enum	itm_addr_t : uint64_t {   k_itm_stim0_addr = 0xE0000000UL ,   k_itm_tcr_addr = 0xE0000E80UL ,   k_itm_tenr_addr = 0xE0000E00UL ,   k_scb_demcr_addr = 0xE000EDFCUL ,   k_sau_type_addr = 0xE000EDD4UL ,   k_ns_sram2_base = 0x32100000UL ,   k_ns_alias_bit = 0x10000000UL }
	ITM / debug PPB addresses and TrustZone alias constants. More...
enum	itm_bits_t : uint32_t {   k_itm_line_max = 240U ,   k_itm_tcr_itmena = 0x00000001U ,   k_itm_tenr_port0 = 0x00000001U ,   k_itm_stim_ready = 0x00000001U ,   k_scb_demcr_trcena = 0x01000000U ,   k_sau_type_regs = 0x00000008U }
	ITM enable-bit values and line sizing for the stimulus echo. More...
enum	console_cfg_t : uint32_t { k_uart_line_max = 512U }
	Console-UART presentation sizing. More...

Functions
void	emu_console_install (uc_engine *uc)
	Seed ITM "ready" bits and arm the stimulus-port echo hook.
void	console_flush_line (uint8_t channel)
	Flush the pending [uart] line to injected output sink with its channel prefix.
void	console_tx_sink (uint8_t channel, uint8_t byte)
	SCI TX sink: print each transmitted byte (prefixed line + raw mirror).
uint32_t	decode_escapes (const char *in, uint8_t *out, uint32_t cap)
	Decode a C-style escaped –input string into a raw byte buffer.
void	emu_console_reset (void)
	Reset the in-flight ITM line (warm-reboot support).

Detailed Description

Emulator text-console surfaces: UART echo, ITM/SWO echo, escapes.

The two text endpoints ra8_emulator surfaces on injected output sink plus the CLI string decoder that feeds them:

• [uart] SCIn: lines – the SCI_B model's transmitted bytes, assembled into lines by the TX sink installed via board_periph_sci_set_tx_sink().
• [itm] ... lines – the Arm CoreSight ITM stimulus-port 0 bytes ra8_log emits, seeded "ready" in PPB RAM and echoed by a memory-write hook (on real hardware these leave through the SWO pin to the J-Link console).
• decode_escapes() – turns a C-style escaped shell argument (--input, --keys, --usb-in) into raw bytes.

Split out of the ra8_emulator main translation unit; behaviour unchanged.

Copyright

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

Since

0.1.0

Definition in file emu_console.h.

Enumeration Type Documentation

console_cfg_t

enum console_cfg_t : uint32_t

Console-UART presentation sizing.

Line-buffer capacity for the pretty [uart] SCIn: echo; also the sizing every CLI byte-injection buffer (--input / --keys / --usb-in) borrows.

Invariant

One line plus its NUL always fits the buffer.

See also

console_tx_sink() Fills the line up to this cap.

Since

0.1.0

Enumerator
k_uart_line_max	Pretty-print line buffer for the [uart] prefix.

Definition at line 91 of file emu_console.h.

itm_addr_t

enum itm_addr_t : uint64_t

ITM / debug PPB addresses and TrustZone alias constants.

The ITM stimulus/control words the seed-and-echo model touches, the DEMCR trace-enable word (shared with the DWT cycle-counter model), and the SAU / Non-secure-alias constants the TrustZone and memory-map code reads from this same historical group.

Invariant

Values are Armv8-M / RA8D2 architectural addresses.

See also

itm_seed_ready() Seeds the enable bits at these addresses.

Since

0.1.0

Enumerator
k_itm_stim0_addr	ITM stimulus port 0 (byte FIFO).
k_itm_tcr_addr	ITM Trace Control Register (ITMENA).
k_itm_tenr_addr	ITM Trace Enable Register (port 0).
k_scb_demcr_addr	Debug Exception + Monitor Control.
k_sau_type_addr	SAU_TYPE (SREGION = implemented regs).
k_ns_sram2_base	SRAM2 Non-secure alias (bit[28]=1).
k_ns_alias_bit	IDAU bit[28]: NS alias of a Secure addr.

Definition at line 48 of file emu_console.h.

itm_bits_t

enum itm_bits_t : uint32_t

ITM enable-bit values and line sizing for the stimulus echo.

The specific bits itm_seed_ready() plants so ra8_log's readiness checks pass, plus the echo line-buffer cap and the SAU region-count seed used by the TrustZone boot path.

Invariant

Values match the Armv8-M ITM / SAU register field definitions.

See also

on_itm_stim_write() Buffers bytes up to k_itm_line_max.

Since

0.1.0

Enumerator
k_itm_line_max	Max chars buffered before a forced flush.
k_itm_tcr_itmena	TCR bit 0: ITM global enable.
k_itm_tenr_port0	TENR bit 0: stimulus port 0 enabled.
k_itm_stim_ready	Non-zero STIM0 read = FIFO ready.
k_scb_demcr_trcena	DEMCR bit 24: trace subsystem enable.
k_sau_type_regs	SAU_TYPE.SREGION: M85 implements 8.

Definition at line 70 of file emu_console.h.

Function Documentation

console_flush_line()

void console_flush_line

(

uint8_t

channel

)

Flush the pending [uart] line to injected output sink with its channel prefix.

Terminates and prints the accumulated line as [uart] SCIn: ...; a no-op when nothing is buffered. The run-end report calls this so bytes emitted without a trailing newline still surface.

Parameters

[in]

channel

SCI channel number used in the printed prefix.

Returns

Nothing.

Precondition

The console TX sink has been collecting bytes (or the buffer is empty).

injected output sink is writable.

Postcondition

The line buffer is empty.

Note

Not thread-safe; the emulator is single-threaded host-side.

See also

console_tx_sink() Fills the buffer this flushes.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 155 of file emu_console.c.

References priv_emu_io_outf(), s_uart_line, and s_uart_line_len.

Referenced by console_tx_sink(), and internal_run_print_stop_summary().

console_tx_sink()

void console_tx_sink	(	uint8_t	channel,
		uint8_t	byte )

SCI TX sink: print each transmitted byte (prefixed line + raw mirror).

Installed via board_periph_sci_set_tx_sink(). Printable bytes accumulate into a line that is flushed – with an [uart] SCIn: prefix – on newline or when the buffer fills, so console output reads cleanly in the log; CR is dropped from the pretty line.

Parameters

[in]	channel	SCI channel that transmitted the byte.
[in]	byte	The transmitted data byte.

Returns

Nothing.

Precondition

The board_periph SCI model routes TX bytes here.

injected output sink is writable.

Postcondition

The byte is buffered or the completed line has been printed.

Note

Not thread-safe; the emulator is single-threaded host-side.

See also

console_flush_line() Forces out a partial line.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 165 of file emu_console.c.

References console_flush_line(), k_uart_line_max, s_uart_line, and s_uart_line_len.

Referenced by internal_main_bringup_peripherals().

decode_escapes()

uint32_t decode_escapes	(	const char *	in,
		uint8_t *	out,
		uint32_t	cap )

Decode a C-style escaped –input string into a raw byte buffer.

Translates \n / \r / \t / \0 / \\ in in so a shell argument can carry the line endings a console example expects (e.g. --input "ping\r\n"); any other character (including an unrecognised escape's backslash) is copied verbatim. Bounded by cap; never overruns.

Parameters

[in]	in	NUL-terminated source string.
[out]	out	Destination byte buffer.
[in]	cap	Capacity of out in bytes.

Returns

Number of bytes written to out.

Return values

0	in was empty (or cap was 0).

Precondition

in is NUL-terminated and out holds at least cap bytes.

cap bounds the write (enforced by the loop condition).

Postcondition

At most cap bytes of out are written.

Note

Pure transformation; thread-safe.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 179 of file emu_console.c.

Referenced by internal_main_feed_inputs().

emu_console_install()

void emu_console_install

(

uc_engine *

uc

)

Seed ITM "ready" bits and arm the stimulus-port echo hook.

On hardware a debugger sets DEMCR.TRCENA and enables the ITM; with none attached those PPB registers read zero and ra8_log drops every byte. ra8_emulator maps the PPB as plain RAM, so this writes the enable bits (DEMCR.TRCENA, ITM TCR.ITMENA, TENR port-0, a ready STIM0) and installs the UC_HOOK_MEM_WRITE echo on the STIM0 word so each emitted line prints as [itm] <line> and lands on the board_console ITM channel. The firmware only ever reads these registers, so the seed persists for the run.

Parameters

[in,out]

uc

Initialised Unicorn engine with the PPB region mapped.

Returns

Nothing.

Precondition

uc has the PPB region (0xE0000000) mapped as RAM.

Called once before emulation starts.

Postcondition

The ITM enable bits are set and the stimulus echo hook is armed.

ra8_log's readiness check returns true for the run.

Note

Not thread-safe; call during single-threaded setup.

See also

console_tx_sink() The UART-side echo counterpart.

Since

0.1.0

Seed ITM "ready" bits and arm the stimulus-port echo hook.

Definition at line 142 of file emu_console.c.

References internal_itm_seed_ready(), internal_on_itm_stim_write(), and k_itm_stim0_addr.

Referenced by internal_main_install_core_seams().

emu_console_reset()

void emu_console_reset

(

void

)

Reset the in-flight ITM line (warm-reboot support).

Drops any partially-assembled [itm] line so a rebooted firmware starts with a clean stimulus stream; the multi-channel board_console store is reset separately by the reboot path.

Returns

Nothing.

Precondition

A warm reboot is re-initialising the console surfaces.

Postcondition

The pending ITM line buffer is empty.

Note

Not thread-safe; the emulator is single-threaded host-side.

See also

emu_console_install() Arms the echo this resets.

Since

0.1.0

Precondition

The call executes on the emulator's single owning thread.

Postcondition

Ownership of caller-supplied storage is unchanged.

Reset the in-flight ITM line (warm-reboot support).

Definition at line 211 of file emu_console.c.

References s_itm_len.

Referenced by warm_reboot().