> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Platform migrations
> Research, plan, implement, and verify firmware migrations across hardware platforms with Embedder while preserving board-level constraints.
Use this workflow to move firmware to another MCU, board, SDK, or hardware revision while preserving the behavior that matters. Embedder can compare the existing code with source and target documentation, prepare a reviewable plan, implement approved changes, and verify the result with project tests and real hardware.
## Define behavioral equivalence first
A migration is complete when the target meets an explicit behavioral contract, not when it merely compiles. Record:
* the source and target MCU, package, board, and board revision;
* the SDK, HAL, RTOS, compiler, linker, and build configuration on each side;
* the public firmware interfaces that must remain compatible;
* required peripherals, pins, clocks, DMA channels, interrupts, and power states;
* timing, throughput, memory, and power budgets;
* boot, flash, debug, and log paths;
* host tests and on-target observations that prove equivalence.
```text theme={"system"}
Migrate the motor-control example from KIT_A2G_TC375_LITE to
KIT_A3G_TC4D7_LITE. Preserve the control-loop API and 10 kHz update rate.
Use only pins routed to the target kit headers, retain serial diagnostics,
and verify PWM timing and fault input behavior on the target board.
```
If a requirement is unknown, mark it unresolved in the plan instead of silently inheriting behavior from the source platform.
## Prepare both sides
Associate the workspace with the Embedder project that represents the source firmware. Run `/init` if `EMBEDDER.md` does not already contain the verified source build, test, flash, and debug workflows.
Select or name the target platform and board revision. Add target documentation or schematics when the catalog and board skills do not provide enough evidence.
Locate the entry points, peripheral abstractions, board layer, clock tree, pin configuration, DMA and interrupt paths, linker layout, startup code, tests, and runtime logs involved in the migration.
Run the smallest tests and hardware observations that define current behavior. Preserve command output, timing, waveforms, serial markers, memory use, or power measurements that the target must match.
Do not begin by copying register values. The same peripheral name can have different clocks, reset sequences, register layouts, interrupt routing, DMA request mappings, and pin alternate functions on the target.
## Compare source and target constraints
Ask Embedder to research before it proposes changes:
```text theme={"system"}
Compare the source UART implementation with the selected target platform.
Identify differences in clocking, reset, register layout, FIFO behavior,
interrupts, DMA requests, pin routing, and error handling. Cite the applicable
source and target documents and list unresolved board-level assumptions.
Do not edit the project.
```
Use a comparison checklist:
| Area | Questions to answer |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| Peripheral instance | Does the target provide the same capability and operating range? |
| Clock and reset | Which source, divider, gate, reset, and startup delays apply? |
| Pin routing | Is the function available on the package and routed to an accessible board pin? |
| Electrical behavior | Do voltage levels, drive strength, pull configuration, and external components differ? |
| Interrupts and DMA | Which vectors, priorities, request lines, descriptors, and cache rules change? |
| Driver boundary | Can the public API stay stable while the platform implementation changes? |
| SDK or HAL | Which generated files, startup conventions, and ownership boundaries apply? |
| Memory and linker | Do regions, alignment, section placement, boot headers, or multicore ownership change? |
| Tooling | Which compiler, build, flasher, debugger, and serial paths are valid for the target? |
| Verification | Which source tests can run unchanged, and which target observations prove equivalent behavior? |
For a custom board, use parsed schematic references to verify connector routing and populated peripherals:
```text theme={"system"}
Compare @sch:component:U1 and @sch:net:CAN_TX with the proposed target pin.
Confirm the transceiver voltage domain and connector path before finalizing
the pin assignment.
```
An MCU package pin is not enough. A valid alternate function may be inaccessible, level-shifted, reserved, or connected to another fitted device.
## Create a migration plan
### Use Plan mode
Run:
```text theme={"system"}
/plan
```
Plan mode can inspect code, documents, schematics, diagnostics, saved traces, serial history, and hardware status. It can modify only the session plan.
Require the plan to include:
1. source and target facts with unresolved assumptions;
2. the selected pins and proof of board accessibility;
3. build-system, startup, linker, and configuration changes;
4. a module-by-module implementation order;
5. tests at each stable boundary;
6. runtime log or measurement points;
7. flash, debug, and rollback requirements;
8. final behavioral-equivalence checks.
```text theme={"system"}
Plan this migration without changing project files. Separate source facts,
target facts, and assumptions. Keep the application-facing driver API stable
where practical. Order the work so each peripheral module builds and has an
isolated test before the next module moves.
```
## Review the plan before execution
Verify these decisions in the plan:
* The target part, package, board, and revision are exact.
* Every proposed pin is reachable and electrically compatible.
* Vendor-generated and hand-maintained code boundaries are explicit.
* The source baseline and target pass criteria use comparable workloads.
* Build and flash commands refer to the target, not the source.
* Destructive setup or generated-file replacement requires review.
* Each implementation step leaves the project in a buildable or testable state.
* A failure has a rollback or diagnosis path.
Ask for changes when the plan hides a hardware choice inside an implementation step.
## Implement module by module
Approve the plan to start the implementation turn in Act mode. Keep changes reviewable:
Configure the target toolchain, startup files, linker script, SDK or HAL, and board selection. Produce the smallest target image before moving application behavior.
Establish a serial, RTT, simulator, or other log path early. A migration without observable runtime state is difficult to verify.
Port one clock, GPIO, transport, storage, or timing module while preserving its application-facing contract where practical.
Run the focused host tests, target build, and one bounded hardware observation for that module. Stop on the first useful failure.
Move consumers only after the lower-level service has evidence on the target.
For an ADS-derived AURIX iLLD project that contains both `.cproject` and `Libraries/iLLD/`, Act mode can run the Windows-only, confirmation-gated `aurix_setup` workflow. It generates CMake and command wrappers from the selected ADS configuration. The generated files contain host-specific paths; regenerate them per workstation and do not commit them.
## Verify the target against the baseline
Use the same observable contract on both platforms:
1. Run unchanged host tests where the platform boundary permits it.
2. Build the intended target configuration and identify its artifact.
3. Flash only the selected board and capture early runtime output.
4. Exercise the same inputs and operating conditions used for the source baseline.
5. Compare protocol traffic, timing, output values, memory use, and power where they are requirements.
6. Record accepted differences and the hardware or documentation evidence that justifies them.
```text theme={"system"}
Build and flash the target image. Capture PWM and the fault input with the
logic analyzer for the same five-second workload used on the source board.
Compare frequency, duty-cycle range, startup ordering, and fault latency.
Report any difference outside the migration plan's tolerances.
```
Switch to Debug mode when equivalence fails and ordinary tests cannot explain why. Use buffered logs and attach-only inspection before resetting a target whose current state is useful evidence.
## Respect platform-specific boundaries
* Board skills provide fixed pinout and tooling context; they do not guarantee every board assembly, silicon step, probe, or toolchain combination.
* Different platform families use different compilers, loaders, debuggers, and startup conventions.
* Embedder does not provide vendor SDKs, compilers, flashers, debuggers, virtual platforms, licenses, or confidential documents.
* There is no automatic platform-diff or code-porting engine. The result depends on the reviewed plan, available source material, project tests, and target evidence.
Compare Plan, Act, and Debug mode boundaries.
Verify target pins, nets, power domains, and board revisions.
Execute the approved plan, build, flash, observe, and debug.