S32Trace Timeline Analysis

Answers execution-profile questions from an S32DS Timeline view export using up to three local inputs: the .timeline file, an optional ELF binary (with DWARF debug info), and an optional project source tree.

When to use

Trigger this skill when the user wants to:

• load a .timeline file and get an overview of CPU time distribution
• find which functions consume the most CPU cycles (hotspot analysis)
• understand the execution sequence - which functions were called in what order
• zoom into a specific time window (by tick range) and see what ran there
• drill into a single function: per-address sample breakdown and source location
• view a source snippet annotated with per-line sample counts
• understand inlined function instances (clamp_i32_0x33d83d24 etc.)

Do not use this skill to configure S32Trace (use s32trace-create-configuration), analyze decoded trace CSV events (use s32trace-analyze-trace), or analyze code coverage from a Flat Profiler export (use s32trace-analyze-coverage).

Available Capabilities

Type	Name	Purpose
MCP tool	search_actions	discover available actions, their input schemas, and descriptions
MCP tool	execute_action	validated dispatcher -- pass action_name + action-specific params

All timeline operations are routed through execute_action:

Action name	Required params	Optional params
timeline.load	timeline_path	elf_path, source_root, extra_source_roots, label, snippet_window
timeline.summary	session_id	source_name, top_k
timeline.hotspots	session_id	sort_by (samples/time), top_k, source_name
timeline.function	session_id, name	source_name, include_source
timeline.window	session_id	start_tick, end_tick, source_name, top_k
timeline.sequence	session_id	source_name, limit
timeline.source	session_id	symbol, file_hint, line, source_name, snippet_window

Call search_actions first (or with a focused query such as "timeline load") to get the full parameter documentation before calling execute_action.

Typical workflow

timeline.load        -> returns session_id + load summary
  -> timeline.summary   (top functions, total samples, timestamp range)
  -> timeline.hotspots  (ranked by samples or time)
  -> timeline.function  (per-function detail + source location)
  -> timeline.window    (zoom into a tick range)
  -> timeline.sequence  (ordered list of function transitions)
  -> timeline.source    (source snippet annotated with samples)

Quickstart

1. Call search_actions(query="timeline load") to confirm the action name and input schema.
2. Ask the user for the .timeline path; ELF and source root are optional but enable richer queries (timeline.function source location, timeline.source).
3. Call execute_action(action_name="timeline.load", params={...}). Record session_id -- it is required by every subsequent call.
4. Unless the user has a specific question, call execute_action(action_name="timeline.summary", params={"session_id": ...}) and present total_samples, timestamp_range, and top_functions_by_samples.

Workflow

1. Identify inputs. Confirm from the user:

   • Absolute path to the .timeline file (timeline_path). Typically at <workspace>/.AnalysisData/<session>/<name>.timeline.
   • (Optional) Absolute path to the ELF with DWARF debug info (elf_path). Required for timeline.function source location and timeline.source.
   • (Optional) Absolute path to the project source root (source_root). Required for timeline.source to return annotated source text.

2. Load the timeline session. Call:

   execute_action(
     action_name = "timeline.load",
     params = {
       "timeline_path": "<absolute path to .timeline>",
       "elf_path":      "<absolute path to .elf>",       // optional
       "source_root":   "<absolute path to project src>", // optional
       "label":         "my_timeline_session"
     }
   )
   

   Verify: function_count > 0, data_row_count > 0. Record timestamp_range for later use in timeline.window.

3. Get an overview. Call timeline.summary unless the user has a precise question. Key fields to present:

   • total_samples and timestamp_range
   • top_functions_by_samples -- where the CPU spent the most cycles

4. Answer specific questions.

   User question	Action to call	Key params
   "Where does the CPU spend most time?"	timeline.hotspots	sort_by="samples"
   "Show me the hottest functions by time"	timeline.hotspots	sort_by="time"
   "How many samples did slow_top get?"	timeline.function	name="slow_top"
   "Show all instances of clamp_i32"	timeline.function	name="clamp_i32"
   "What ran between tick 1000 and 50000?"	timeline.window	start_tick=1000, end_tick=50000
   "Show me the execution sequence"	timeline.sequence	limit=200
   "Show slow_top source with samples"	timeline.source	symbol="slow_top"
   "Show line 42 of workloads.c"	timeline.source	file_hint="workloads.c", line=42

5. Inline function handling. The timeline function table lists inlined copies under names like clamp_i32_0x33d83d24. When the user asks about clamp_i32:

   1. Call timeline.function(name="clamp_i32") -- it matches all instances whose name is exactly clamp_i32 or starts with clamp_i32_0x.
   2. Each instance in the instances list has its own address, size, and total_samples.
   3. Note that different instances may have very different sample counts because each is a separate copy of the inlined function placed at a different call site.

6. Time-window drill-down. Use timestamp_range from timeline.summary to orient the user:

   1. Present [start, end] range with the unit note that it is raw tick counts (unit depends on board timestamp generator configuration).
   2. Let the user pick a sub-range, then call timeline.window with those bounds.
   3. Compare the per-window hotspot list to the full-trace list to show what changed.

Guardrails

Scope

• All timeline actions are read-only; no file is written, no project is modified, and no S32 Design Studio process is started.
• Do not call configurator actions (configurator.*) from this skill.

Destructive actions

• None. timeline.load writes only to an in-memory session cache keyed by session_id; it does not touch any file.

Secrets

• No secrets or PII are involved; no redaction required.

Refuse-and-escalate

• timeline.load returns error: report the message verbatim and ask the user to verify the file path.
• timeline.function returns found: false: confirm the exact function name using timeline.summary or timeline.hotspots first.
• timeline.source returns error about missing ELF or source root: ask the user to reload with elf_path and source_root provided.
• Stale session_id: if an action returns "Timeline session ... not found", the MCP server was restarted; call timeline.load again and record the new session_id.

Resource limits

• Default top_k for hotspots and summary is 10. Increase only when the user explicitly asks for more.
• timeline.sequence default limit is 100 transitions. Raise only on request.

Validation loop

1. After timeline.load, verify function_count > 0 and data_row_count > 0.
2. After timeline.summary, confirm total_samples > 0.
3. Pass criterion: session_id is in hand, function count and row count are non-zero, and the timestamp range is plausible.

Out of scope

• Creating or editing S32Trace configuration XML (use s32trace-create-configuration).
• Trace event analysis from a decoded CSV (use s32trace-analyze-trace).
• Code coverage analysis from a Flat Profiler export (use s32trace-analyze-coverage).
• Installing or updating S32 Design Studio.
• Compiling, flashing, or debugging firmware.

See Also

• search_actions(query="timeline") -- returns the full parameter schema for all 7 timeline.* actions.
• s32trace-analyze-trace -- sibling skill for trace event / timing analysis from CSV.
• s32trace-analyze-coverage -- sibling skill for code coverage from Flat Profiler.
• s32trace-create-configuration -- skill for configuring the trace capture.