Migration Guide

This page collects migration guidance for users moving between TEMU API and configuration styles.

The intent is to keep legacy code and scripts working where practical, while still encouraging migration to the newer interfaces.

C API Compatibility Headers

The public C API includes compatibility headers for older object-typing conventions:

  • temu-c/Support/Temu2Compat.h

  • temu-c/Support/Temu3Compat.h

These headers are included from core public headers such as temu-c/Support/Objsys.h.

The compatibility mode is controlled by defining TEMU_TYPE_ERASED_OBJECTS before including the TEMU headers.

#define TEMU_TYPE_ERASED_OBJECTS
#include "temu-c/Support/Objsys.h"

With TEMU_TYPE_ERASED_OBJECTS enabled, older code that expects type-erased void *-style object and time-source arguments can be kept source-compatible while it is being migrated to the typed temu_Object *, temu_Component *, and temu_TimeSource * forms used by newer TEMU releases.

Recommended migration strategy:

  • keep the compatibility macro enabled while first moving to a newer TEMU release

  • update model code to use the typed object pointers directly

  • remove TEMU_TYPE_ERASED_OBJECTS once the codebase no longer depends on the legacy calling convention

See Libraries for the general API compatibility and deprecation policy.

Script and System Migration

Older TEMU setups often construct complete boards through legacy sysconfig scripts. Newer setups should prefer YAML components, which are easier to maintain and compose.

For example, instead of constructing a whole machine through a large hand-written script, use:

import Component
Component.new name=board0 file=components/board.yaml

See Components for the component model.

Object Naming Differences

Component instantiation intentionally namespaces contained objects. For example, a CPU that previously appeared as cpu0 in a legacy system script may instead appear as board0-cpu0 when instantiated from a component named board0.

To help with migration, TEMU supports object aliases. This allows compatibility wrappers to preserve older object names while still using YAML components as the source of truth.

import Component
Component.new name=board0 file=components/gr740.yaml

alias name=cpu0 object=board0-cpu0
alias name=mem0 object=board0-mem

This is particularly useful for:

  • regression tests that still look up cpu0, mem0, or similar names

  • legacy board scripts kept as thin wrappers around component instantiation

  • staged migrations where new code uses component-qualified names and old code still uses legacy names

Recommended migration strategy:

  • keep board topology in YAML components

  • keep legacy sysconfig files only as compatibility wrappers where needed

  • use object aliases to preserve old global names when required

  • update new scripts and tests to use component-qualified names directly

Reset Semantics for Migrated Bundled Sysconfigs

When a bundled legacy sysconfig has been migrated to instantiate a YAML component, board-wide reset behavior may move from CPU-local reset fanout to the component’s exported reset path, typically via a reset controller inside the component.

In practice, this means that scripts using migrated bundled sysconfigs may need to prefer:

reset obj=board0 warm=0

instead of:

reset cpu=cpu0 warm=0

for board-level reset behavior.

This change only applies to the bundled sysconfigs that TEMU has migrated to component-backed wrappers. Customer-owned legacy sysconfig scripts are not affected unless they are updated to use the bundled component-backed wrappers or otherwise adopt the same component/reset-controller structure.

Command Aliasing Compatibility

The alias command now supports command, class, and object aliasing:

alias name=my_echo command=echo
alias name=LegacyScheduler class=SingleLevelScheduler
alias name=cpu0 object=board0-cpu0

Legacy command-alias handling can be controlled through the compatibility configuration key:

compatibility/commands/alias

This key is versioned. For command aliasing only:

  • values ⇐ 4 preserve the older behavior where aliasing an unknown command reports a diagnostic but does not fail the script

  • values >= 5 use the newer strict behavior where aliasing an unknown command fails

This setting can be placed in a user configuration file or in a project file.

compatibility:
  commands:
    alias: 4

See Configuration System and Project Files for configuration layering and project scoping.

Recommended Approach

For actively maintained codebases:

  • use the typed C API instead of relying on TEMU_TYPE_ERASED_OBJECTS

  • use YAML components as the primary board description format

  • keep compatibility settings and aliases only where they are needed for existing tests, scripts, or customer integrations

  • remove compatibility layers incrementally once dependent code has been migrated