S32CT Clocks Graft / Tune .mex

Edit the <clock_configuration> block of a .mex in one of three modes: apply a validated performance preset, tweak individual <setting id value/> entries, or lift a whole <clock_configuration> from an example .mex. Optionally adds McuClockReferencePoint_* entries so driver *ClockRef settings map to the right domain. Sibling of s32ct-peripherals-graft-mex: same "lift validated XML, adapt, validate" workflow applied to the Clocks tool.

When to use

• Use for: user names the Clocks tool or a clock frequency; a driver's runtime behaviour (baud rate, PWM resolution, ADC conversion time) depends on a clock domain that the default McuClockReferencePoint_0 -> CORE_CLK shortcut gets wrong; peripheral performance higher than the template default is required; a new McuClockReferencePoint_* is needed for a driver instance.
• Do not use this skill for: Pins or Peripherals changes (use s32ct-pins-author-mex / s32ct-peripherals-author-mex / s32ct-peripherals-graft-mex); read-only queries (use s32ct-clocks-info / s32ct.inspect_clock_outputs); adding a second <clock_configuration> sibling - see references/multi-config.md.

Available Capabilities

Type	Name	Invocation
MCP tool	the s32ct.inspect_* actions	Read query=clock_outputs / clock_settings / clock_points / xrefs.
MCP tool	s32ct.lookup_enum_values	Legal values for a setting on this package.
MCP tool	s32ct.sanitize	Post-lift normalisation of Mcu/Mcl cross-refs.
MCP tool	s32ct.validate	Validation gate. tool_name="Clocks" for fast iteration.
MCP action	nxp_s32ct_execute_action(action_name="s32ct.generate_code", params={...})	Emit Mcu_Cfg.[ch].
Script	scripts/inspect_clocks.py	Standalone query=clock_* equivalent.
Script	scripts/apply_settings.py	Apply preset or (id, value) edits. Idempotent.
Script	scripts/lift_clockconfig.py	Extract <clock_configuration> from an example.
Script	scripts/add_clock_point.py	Add a McuClockReferencePoint_*.

Quickstart

Shell: examples use Windows cmd.exe line continuation ^; on POSIX shells (bash/zsh) replace ^ with \.

1. Inspect the current clock state:

   python scripts/inspect_clocks.py project.mex --query clock_outputs
   

2. Choose a mode: preset, tweak, or lift.

3. mode=preset (most common - "make this fast"):

   python scripts/apply_settings.py project.mex ^
       --preset s32k312:max_performance ^
       --out    project.tuned.mex
   

4. mode=tweak - bump one setting:

   python scripts/apply_settings.py project.mex ^
       --set CORE_MFD.scale=40 ^
       --set MC_CGM_MUX_0_DIV0.scale=1 ^
       --out project.tuned.mex
   

5. mode=lift - graft the K344 example's clock tree:

   python scripts/lift_clockconfig.py project.mex ^
       --example ".../S32K344/RTD/example.mex" ^
       --out     project.tuned.mex
   

6. Sanitize (only after lift) and validate - first Clocks, then Peripherals + Pins for regression:

   s32ct.sanitize(project_path=project.tuned.mex)
   s32ct.validate(project_path=project.tuned.mex, tool_name="Clocks")
   s32ct.validate(project_path=project.tuned.mex)
   

7. Optional - add semantic clock points so driver *ClockRef values can point at the right domain:

   python scripts/add_clock_point.py project.tuned.mex ^
       --name LPUART_CLK  --select AIPS_SLOW_CLK ^
       --name LPSPI_CLK   --select AIPS_PLAT_CLK ^
       --name CAN_PE_CLK  --select AIPS_PLAT_CLK ^
       --name EMIOS_CLK   --select AIPS_PLAT_CLK ^
       --out  project.final.mex
   

Full workflows (A / B / C), setting-id conventions, and the preset tables are in references/.

Configuration

Core inputs (see references/configuration.md for the full input table and the tweak / clock-point schemas):

• project_path, output_path -- absolute paths.
• mode -- preset | tweak | lift.
• mcu, package -- e.g. S32K312, S32K312_172HDQFP.
• preset -- one of the four presets (mode=preset).
• tweaks -- array of { type, id, value, [from, to] } (mode=tweak).
• example_mex -- source .mex (mode=lift).
• add_clock_points -- optional McuClockReferencePoint_* entries.
• platform_sdk / rtd_version / s32ds_install -- auto-discovered.
• validate, overwrite -- default true / false.

Enumerate legal tweak.id values on this package with s32ct.inspect_clock_settings.

Guardrails

Scope. Writes only to output_path. Uses s32ct.sanitize to rewrite dangling Mcu/Mcl references introduced by a lift. Never touches target hardware; CLI invocations are read-only on the filesystem apart from output_path and validator capture files.

Destructive actions. Refuses to overwrite an existing output_path unless overwrite=true. Refuses values above declared datasheet ceilings - the validator only enforces syntactic correctness; pushing beyond a datasheet ceiling causes silent silicon failure. Presets are pre-clamped; freestyle values that exceed the clamp are rejected.

Refuse-and-escalate. Refuses when the .mex fails Pins or Peripherals validation before editing - clocks changes on a broken .mex produce misleading diffs. Refuses when a tweak.id does not exist for the target package (cross-check with the s32ct.inspect_* actions). Refuses to invent numeric values not present in a validated example or documented preset - freestyle overrides need explicit user intent.

Validation loop

1. s32ct.inspect_clock_outputs before editing - baseline.
2. Apply the chosen workflow (preset / tweak / lift). After a lift, run s32ct.sanitize to fix cross-references.
3. s32ct.validate(tool_name="Clocks") - fast iteration. Uses the same 4-step stderr-capture / noise-filter procedure as the driver graft skill; valid: true = filtered stderr empty AND exit_code == 0. The launcher (toolsc.exe / s32dsc.exe - see s32ct-distributions) always returns 0, so exit code alone is insufficient.
4. s32ct.validate without tool_name - full regression across Pins + Peripherals + Clocks. Driver instances reference clock-tree elements; a removed output id will break them.
5. s32ct.inspect_clock_outputs after editing with diff_against=<baseline> to confirm intended before/after delta.
6. Pass = Clocks + full regression clean AND before/after matches intent. Fail = surface filtered stderr verbatim and consult references/error-decision-tree.md.

Out of scope

• Pins or Peripherals tool changes.
• Read-only queries about the current clock state (use s32ct-clocks-info / the s32ct.inspect_* actions).
• Adding a second <clock_configuration> sibling - see references/multi-config.md.
• Retargeting driver *ClockRef values themselves. This skill adds the semantic clock points; re-pointing each driver instance is a search/replace step handled by the caller (or the driver-graft skill).
• Datasheet-forbidden frequencies. The validator accepts syntactically valid but physically illegal values - the presets are pre-clamped; freestyle overrides beyond the clamp are refused.

See Also

• references/clock-anatomy.md - S32CT clock data model: TOP.xml, FXOSC.xml, MODULE_CLOCKS.xml, <configuration_element>, <selector>, <configurable_clock_source>, and how <setting id> maps to them. Read on the first clocks task or when a new setting id surfaces.
• references/performance-presets.md - per-MCU-family preset tables (max-perf / mid-perf / low-power-run / safe): (setting_id, value) tuples plus before/after frequency tables.
• references/error-decision-tree.md - Clocks-tool validation errors and their fixes. Read on any unrecognised SEVERE: [TOOL] line.
• references/multi-config.md - adding a second <clock_configuration> (e.g. LowPower) for runtime mode switching.
• Related skills: s32ct-peripherals-graft-mex (driver-side companion), s32ct-clocks-info (read-only knowledge), s32ct-pins-author-mex (EXTAL/XTAL routing when enabling new oscillators), s32ct-generate-code (emit Mcu_Cfg.[ch]), s32ct-distributions (install-root discovery).