General Usage

Start TEMU from the project directory:

The project file applies the project search paths, runtime directories, and startup scripts. In the generated tutorial project, scripts/temu/imports.temu imports component support and scripts/temu/startup.temu initializes the scheduler, creates board0, and adds the board CPU to the scheduler:

The component owns the board objects, so the CPU and memory space are named board0-cpu and board0-mem. The scheduler object is named sched.

The relevant startup commands are:

TEMU 5 runs target processors through a scheduler. If you create a project manually, call init-scheduler before running software and add every processor that should execute with sched.add-cpu. The generated project startup script does this for the tutorial board.

Target software is loaded into an object that implements the memory interface. For the tutorial LEON3 board, use the component memory space:

If the image contains an entry point, TEMU will use it when the loader supports that format. You can inspect or adjust the CPU state before running:

The tutorial project uses the multi-level scheduler. After loading software and finishing scheduler configuration, start the scheduler once:

Then use the normal execution commands. run, step, trace, and stop are the preferred user-facing commands, also when the active scheduler is the multi-level scheduler. They route execution through the scheduler that was configured during startup:

Use step when you need instruction-level control for one processor. Other processors in the scheduler may still run when the step crosses a scheduler quantum:

Use stop to request that a running multi-level scheduler stops.

When a program stops because of a trap, breakpoint, or error mode, inspect the CPU and disassemble around the program counter:

Use the scheduler object explicitly in startup scripts for scheduler configuration, and use the top-level execution commands for normal interactive work.

The scheduler quantum controls how far processors can run before the scheduler synchronizes time and dispatches pending synchronized events. Larger quanta reduce scheduler overhead, while smaller quanta make cross-processor and event timing synchronization more frequent.

For the default single-domain tutorial board, adding the CPU is enough:

If no domains are configured, the multi-level scheduler creates a default domain when it starts. To choose a CPU quantum explicitly, create a leaf domain and assign the CPU to it before sched.start:

For systems with several processors, add every processor before starting the scheduler. For a normal multi-core board, the usual deterministic setup is to place all CPUs for that board in the same leaf domain and run that domain with one worker thread. This keeps the CPUs ordered by the scheduler instead of by host-thread timing:

You can create more workers for higher performance, for example one worker per CPU in a large leaf domain. That trades determinism for speed because host-thread scheduling can affect the order in which runnable CPUs make progress.

Use explicit domains when groups of processors need their own synchronization quantum. A leaf domain owns processors. A parent domain synchronizes child domains at a coarser boundary:

In this example, board0-cpu0 synchronizes at 1000-cycle leaf boundaries, board0-cpu1 synchronizes at 2000-cycle leaf boundaries, and both domains meet at the 50000-cycle parent-domain boundary. Domains, CPU assignment, domain worker counts, and domain frequencies must be configured before sched.start. Use sched.set-domain-workers id=…​ workers=…​ and sched.set-domain-frequency id=…​ frequency=…​ for those optional domain settings.

For multi-board simulations, a common deterministic layout is one leaf domain per board. Put the CPUs of each board in that board’s leaf domain, run each board domain with one worker, and connect the boards through delay/replay-capable links so cross-board traffic is recorded and delivered at deterministic synchronization points. The domain quantum should be chosen together with the link latency; cross-domain communication needs enough delay that delivery can be ordered at domain boundaries.

Multi-board systems do not have to use separate domains. If deterministic ordering is more important than parallelism, or if the board-to-board communication is too tightly coupled for delayed links, put all board CPUs in a single leaf domain and run it with one worker.

The object system is the main way to inspect a running simulation. Use object-list to find object names and info to inspect one object:

Use class-info when you need to know which properties, interfaces, and ports a class provides:

Properties can also be read and written directly:

The memory space can print its current mappings:

This is useful before adding a device model, but it is also useful during normal usage because it shows which address ranges are occupied by ROM, RAM, and peripherals.

The CPU-specific assembler and disassembler can be used for small experiments:

Snapshots let you preserve a configured or partially executed system. Project scaffolds place runtime files below .temu/, so this tutorial saves snapshots there:

The snapshot stores the object graph and properties, in a binary format.

Projects can define named targets for common workflows. If a project contains a target named hello, start it directly from the shell:

Use targets for repeatable usage flows such as loading one software image, setting up a debugger, or running a test script. Keep ad-hoc interactive experiments in the shell until the command sequence is stable enough to move into a project startup script.