Interface Modes Overview

EMU’s workflow is divided into four distinct operational modes: Design, Driver, Emulate, and Observe. Each mode serves a specific phase of the virtualization lifecycle, from initial hardware mapping to live execution.

Design Mode: The Interface Blueprint

Design Mode is where you define the architectural blueprint of your virtual hardware. It establishes the fundamental rules: what system calls constitute your hardware interface, what memory shapes they use, and how data flows.

Hardware Spec Management (Left Panel)

• Search & Filter: Quickly isolate specifications by type (e.g., ioctl), Group ID, or Alias.
• Auto-Import from Capture (Magic Wand): Automatically generates a new spec based on a live capture feed, populating the System Call Type and Hardware Code.

Global Identity (The Core Hook)

Defines the mechanical trigger for the system call:

• System Call Type: The POSIX operation (e.g., open, read, ioctl).
• Data Capture Phase: * Outbound (Pre-Kernel): Application pushing data out.
  • Inbound (Post-Kernel): Application requesting data from the system.
• Hardware Code & Label: The hex signature (e.g., 0x81785501) and its C-macro label (e.g., SNDRV_CTL_IOCTL_CARD_INFO).

Argument Specifications & Payloads

• Payload Data Type: Links the primary payload to a specific C-schema.
• Argument Specifications: Defines data types for every variable or nested pointer passed in the call.

Driver Mode: Programming the Behavior

If Design Mode is the blueprint, Driver Mode is the brain. Here, you write the TCL scripts that dictate how the mock hardware responds.

TCL Scripting Console

• The Environment: Supports standard TCL plus EMU extensions like certo::payload_data::* and certo::force_return_value.
• Validate Syntax: Runs static analysis without saving.
• Apply: Hot-reloads the updated logic directly into the running engine.

Emulated Hardware Output (Isolated Logging)

To avoid the “noise” of global system traffic, this window only displays output (puts) and error traces related to the specific script you are editing.

Hardware Driver vs Software Driver

Driver Mode has two sub-modes controlled by the Driver Mode toggle in the toolbar.

The two modes use separate script fields because the semantics of “inbound” and “outbound” reverse completely. A single shared script would be ambiguous about which direction it describes.

When software driver mode is active, the Design Mode panel shows an additional Software Driver Script editor (amber border) alongside the Hardware Behavior Script. Both can be authored independently.

See Software Driver Mode for a full explanation, worked examples, and the emu shell --software-driver CLI workflow.

Emulate Mode: Live Execution & Overrides

This is the live control center where you toggle behaviors and monitor performance.

Emulation Activation & Metrics

• Emulation Enabled Toggle: Explicitly injects your TCL script into the execution pipeline.
• Avg Round Trip Time: Total latency from capture to returning the result to the app.
• Avg TCL Exec Time: The specific time taken by your script logic.

Pure Virtual Emulation

When enabled, EMU isolates the application from the host OS hardware stack entirely. The app no longer requires physical file paths or host drivers; everything is satisfied in user-space.

Observe Mode: Telemetry & Inspection

The primary diagnostic window providing a chronological feed of every system call.

Discovery & Linking

• Add as New: Convert an unmapped call into a Design Mode spec.
• Link to Existing: Map a new memory offset to a previously defined hardware spec.

Call Inspection & Metrics

Clicking a call provides:

• Metadata: Unique Call ID, PID, and precise Timestamps.
• Memory Payload Inspection: Parses raw bytes against your C-schema into a human-readable structure.

Status Bar & Global Logs

Located at the bottom of the interface, providing persistent context:

• Workspace Context: Shows Active Mode and the current .vhb project file.
• Unified Console: Access to Engine logs, UI logs, and the Target Process (stdout/stderr of the app being tested).

EMU Desktop Wrapper

The outer shell managing global state, identity, and licensing.

Settings Modal