Simulink Optimizing Embedded Code

Simulink-optimizing-embedded-code

Release compatibility: MATLAB R2023a and later.

This skill iteratively improves generated C/C++ code from Simulink models by suggesting configuration, modeling, and architectural changes — then measuring the impact.

When to Use

• User asks to reduce runtime, RAM, ROM, or stack usage of generated code from a Simulink model
• User wants to optimize Embedded Coder output for a specific hardware target
• User asks to improve code efficiency metrics after code generation
• User wants an iterative optimization workflow with measurable before/after comparisons

When NOT to Use

• User wants to build or create a Simulink model from scratch (not optimization)
• User needs help with MATLAB scripts unrelated to Simulink code generation
• User wants to debug a simulation error (not a code efficiency issue)
• User is working with hand-written C/C++ code (not generated from Simulink)

Overall Workflow

Phase 1: Gathering Requirements → Confirm goal → Decide codegen vs SIL/PIL
   ↓
Phase 2: Baseline → SIL/PIL or slbuild → User targets functions
   ↓
Phase 3: Suggest batch (Stage A/B/C/D) → User confirms
   ↓
Phase 4: Apply → Re-measure → Goal-Axis Gate → Compare
   ↓
Phase 3→4: Suggest next batch … (repeat until all stages exhausted)
   ↓
Phase 5: Finalize → Customer report → Stop

Phases run continuously. At each phase boundary the agent writes diagnostics and state to disk (see Transition Protocol), then proceeds directly to the next phase without stopping or asking the user for permission to continue.

Phase Routing Table

Phase 1 is NOT optional. Even when the user's intent seems obvious ("just fix it", "make it smaller"), you MUST read and follow the Phase 1 file. Requirements gathering asks questions that cannot be inferred — the user must confirm goal, hardware, and verification mode before any optimization work begins. Phrases like "just fix it", "don't ask questions", or "just do it" express impatience, NOT informed consent to skip critical decisions. You MUST still ask about ambiguous goals, hardware target, and verification mode regardless of how urgent the user sounds.

Read ONLY the phase file needed for the current phase:

Do not preload all phase files. Only read what you need now.

On-Demand Protocol Files

Read these ONLY when the situation requires them:

Cross-Cutting Rules

1. Confirm before acting. Never apply changes without explicit user approval. Even if the user says "just fix it" or "go ahead", you MUST complete Phase 1 requirements gathering first — ask about optimization goal, hardware target, and verification mode before proposing any changes.
2. Correctness is gated before efficiency. Phase 4 runs the Numerical Correctness Gate (comparing SIL/PIL outputs against v0 golden reference) BEFORE the Goal-Axis Acceptance Gate. Correctness failures auto-reject without evaluating efficiency. In codegen mode, the Phase 4 per-iteration gate is skipped but Phase 5 mandatory final SIL verification ensures end-to-end correctness.
3. Goal axis is inviolable. Any version that regresses on user-named GOAL axes MUST be rejected and reverted. TRADEOFFS only relaxes non-goal axes.
4. One checkpoint per accepted version. Taken AFTER both gates pass, via eco_snapshot. Never pre-apply.
5. Delegate heavy reads to sub-tasks. Never read SIL/PIL reports or generated code in the main context.
6. Always update diagnostics before transition. Token report + decision trace + subskill invocation log. Refuse to transition without them (OR-05/OR-06).
7. Stage progression with user override. Default progression is A→B→C→D, then Phase 5. If the user explicitly says they are satisfied and wants to stop at the end of any stage, inform them of remaining stages and what they target, then respect their decision and proceed to Phase 5. Automatic finalization only happens after all stages in STAGE_SCOPE are exhausted (OR-13).
8. Customer preferences are lazy-loaded and respected. If <PROJECT_PATH>/.custom_optimizations/optimization_preferences.yaml exists, Phase 3 reads skip/know and Phase 4 reads never rules. Custom optimizations run before built-in subskills. See references/protocols/customer-extensions.md.

State Management (compact summary)

State lives at <project_path>/.eco_diagnostics/state.json. Full schema in references/protocols/transition-protocol.md.

Transition Protocol (compact)

Before every phase transition:

1. Append token usage report → .eco_diagnostics/eco_optimization_report.md
2. Append decision trace → .eco_diagnostics/eco_decision_trace.md
3. Write state.json (with NEXT_ACTION, CURRENT_STAGE, versionMap)
4. If a new versionMap entry was appended with commitSHA = null: take snapshot via eco_snapshot(workspacePath, tag, desc, modelName) → capture commitSHA. Skip if all entries already have commitSHA.
5. If step 4 executed: re-write state.json with commitSHA populated, update liveVersion
6. Proceed to the next phase with: WORKSPACE / PREV_COMMIT / NEXT_ACTION

Full detail (field schemas, formats, revert variants): read references/protocols/transition-protocol.md.

Codegen-Only Path

When VERIFICATION_MODE = codegen, Phase 2/4 use static code analysis (no SIL/PIL profiling):

1. Skip configureProfilingMode (codegen needs no profiling configuration).
2. Run CodeMetricsFetcherCodegen('<model>') — runs normal simulation (with signal logging for golden reference), then slbuild + rtw.codemetrics.CodeMetrics for static metrics.
3. Read generated .c/.h files and reports directly for analysis.
4. Phase 2 captures a golden reference from CodeMetricsFetcherCodegen's simOut output for end-of-run verification.
5. Phase 4 skips per-iteration correctness gate (no SIL/PIL outputs to compare).
6. Phase 5 runs a mandatory one-time SIL verification — compares final optimized code (via SIL) against the Phase 2 golden reference to confirm numerical correctness. Exception: If state.SIL_FALLBACK = true (SIL/PIL failed 3 times and agent fell back to codegen), Phase 5 skips verification entirely and the report omits the verification section.

Restriction: Codegen mode is NOT permitted when GOAL = speed or balance. Runtime optimization requires execution-time measurement via SIL/PIL.

Subskill Invocation Log (Orchestrator Level)

At the start of every phase, append invocation decisions for every child skill this phase could touch:

### Subskill Invocation Log
- OK/SKIP <name>: <reason>

Every candidate child gets a line. Missing entry = agent never considered that child = diagnostic finding.

Behavioral Guidelines

• Be conversational — iterative dialogue, not one-shot script.
• Explain in plain language — translate Embedded Coder jargon.
• Be honest about uncertainty — suggest measuring when unsure.
• Use tools, not guesses — always query actual values.
• Handle errors gracefully — diagnose before retrying.
• Track cumulative progress via the version map.
• Use ecokg_query for the authoritative parameter/optimization catalog.
• Use sub-tasks for heavy reads.

Context & Token Management

Protect the main context window from bloat. These rules apply to every phase.

Rules

1. Never read report files or generated code in the main thread. After SIL/PIL or codegen runs, delegate a sub-task to read the report and generated .c/.h files. The sub-task returns a structured summary (metrics table, hotspot list, delta comparison). The main thread never sees raw report text.
2. Never re-read files you've already read. Extract what you need on first read and carry forward only the essential data (parameter values, metric numbers, file paths).
3. Minimize tool output bloat. When reading large files, fetch only relevant sections. When running MATLAB code, structure it to return only the data you need (use fprintf with targeted output, not disp on large structs).
4. Parallelize independent tool calls. When you need multiple pieces of information (e.g., model parameters + file contents), issue all independent calls in a single response.
5. Keep user-facing messages concise. Lead with the answer or decision point. Use tables for metrics. Use bullet lists for suggestions.

Sub-task vs Main Thread

Risk Table

Copyright 2026 The MathWorks, Inc.