S32CT Pins .mex Authoring

Author a Pins-tool .mex for a given (MCU, package, platform_sdk) triple from a board description (schematic PDF or explicit routings). The skill orchestrates three lower-level skills in order: enumerate legal routings, clone a reference template and patch in <pin> entries, then validate with stderr capture. Works for any MCU for which a reference .mex template has been registered with s32ct-generate-mex-config.

When to use

• Use for: "make a Pins .mex for board X with <peripheral list>", "configure pins for <peripherals> on this EVB", "generate the Pins config that matches this schematic", "bring up Pins for <MCU> on <board> using RTD <version>".
• Do not use this skill for: Clocks-tool authoring (s32ct-clocks-graft-mex), Peripherals-tool authoring (s32ct-peripherals-author-mex), driver-source generation (s32ct-generate-code), interactive routing exploration only (s32ct-pins-info alone), or targets for which no reference template exists (see references/authoring-procedure.md section Extending to a new MCU/RTD/package).

Available Capabilities

Type	Name	Invocation
Sub-skill	s32ct-pins-info	Enumerate legal (peripheral, signal, pin) triples.
Sub-skill	s32ct-generate-mex-config	Clone reference .mex, patch <pin> block.
MCP action	nxp_s32ct_execute_action(action_name="s32ct.configure_pins", params={...})	Headless validation (-ShowProblems).
MCP action	nxp_s32ct_execute_action(action_name="s32ct.generate_code", params={...})	Optional: emit Siul2_Port_Ip_Cfg.[ch].

Quickstart

1. Collect inputs: board_name, mcu, package, platform_sdk, output_path, and either schematic_path (PDF/folder) or an explicit routings list. Optional: peripheral_request quota (e.g. { "SPI": 2, "UART": 2, "CAN": 2, "LIN": 2, "ADC": 2, "PWM": 1 }).

2. Enumerate legal routings for the target and cross-check every candidate (peripheral, signal, pin):

   // s32ct-pins-info payload
   { "mcu": "S32K312",
     "package": "S32K312_172HDQFP",
     "platform_sdk": "PlatformSDK_S32K3",
     "filter": { "peripheral": "LPSPI0" } }
   

3. Resolve conflicts in the fixed greedy order ADC -> CAN -> LPSPI -> LPUART -> PWM. See references/authoring-procedure.md for the full algorithm and <pin> shape.

4. Clone the reference template and patch in the <pin> block:

   // s32ct-generate-mex-config payload
   { "mcu": "S32K312", "package": "S32K312_172HDQFP",
     "platform_sdk": "PlatformSDK_S32K3",
     "output_path": "<output_path>",
     "modifications": { "pins": "<literal <pin> block>",
                        "common": { "description":
                          "Board-tailored: <board> - <request-summary>" } },
     "regenerate_uuid": true, "copy_sidecars": true }
   

5. Validate with stderr capture (exit code alone is not sufficient):

   { "action": "pins",
     "project_path": "<output_path>",
     "extra_args": ["-ShowProblems"] }
   

   Apply the four-step stderr filter documented in references/authoring-procedure.md (section Validation recipe).

6. Optional - emit driver sources:

   { "action": "generate_code",
     "project_path": "<output_path>",
     "tool_name": "Pins", "export_kind": "ExportSrc",
     "output_dir": "<dirname(output_path)>/generated_pins" }
   

Configuration

Key inputs (full table in references/authoring-procedure.md):

Name	Required	Notes
board_name	yes	Human label, used only in the report.
schematic_path	conditional	Required when routings is not supplied.
routings	conditional	Explicit override, bypasses schematic parsing.
peripheral_request	yes when parsing schematic	Quota per family.
mcu, package	yes	Case-sensitive folder names.
platform_sdk	no	Defaults to the sole subfolder when unambiguous.
output_path	yes	Absolute path for the generated .mex.
prefer_onboard	no	Default true.
regenerate_uuid	no	Default true.
validate	no	Default true.
generate_sources	no	Default false.
overwrite	no	Default false.

Guardrails

Scope. Writes only to output_path, its sibling ClockConfigurationMappings.txt, and (when generate_sources=true) the generated_pins/ directory. Does not modify the bundled template .mex or signal_configuration.xml. Does not touch hardware, registers, FreeMASTER, or any running process.

Destructive actions. Refuses to overwrite an existing output_path unless overwrite=true. Refuses to silently drop a requested peripheral when no conflict-free routing exists - returns an error listing the conflicts so the caller can reduce the request or supply an explicit routings override.

Refuse-and-escalate. Refuses when no reference .mex template is registered for the (mcu, package, platform_sdk) triple; escalates to the Extending to a new MCU/RTD/package section of references/authoring-procedure.md. Refuses when neither schematic_path nor routings is supplied. Propagates inner-skill errors verbatim, prefixed with the offending step.

Validation loop

1. Run headless validation with stderr redirected to file (a one-line .bat wrapper is often needed because cmd evaluates 2>file only with non-spaced paths - copy the .mex to a spaceless path first if the install path has spaces).
2. Grep captured stderr for SEVERE: [TOOL] and SEVERE: [Generation. Exit code alone is unreliable: toolsc.exe returns 0 even when the Problems View contains errors.
3. Filter out generic Eclipse/framework noise (SEVERE: Cannot get container for IPath ..., SEVERE: ... SerDes Config Tool when SerDes is not enabled, SEVERE: Error in expression parsing ... featureDefined, SEVERE: Problem occurred during invocation of function derefAsr). The precise filter list is in references/authoring-procedure.md.
4. Pass = filtered output is empty AND exit_code == 0. Fail = any line remains - surface verbatim in the Validation result section of the report and keep the file on disk.

Out of scope

• Configuring the Clocks or Peripherals tools.
• Generating driver C sources without a preceding valid .mex (call s32ct-generate-code afterwards).
• Interactive routing exploration (use s32ct-pins-info alone).
• Authoring for MCU/package/SDK triples with no registered reference template - see references/authoring-procedure.md.
• Modifying target hardware or running code on the MCU.

See Also

• references/authoring-procedure.md - full step-by-step procedure: schematic parsing, XML cross-check rules, conflict resolution order, <pin> element shape, direction defaults, template registry, the four-step validation recipe, error-message templates, and the Extending to a new MCU/RTD/package recipe.
• references/agent-reasoning-notes.md - long-form rationale: case rules for peripheral= / signal= / pin_signal= / pin_num, channel-attribute rule, why the greedy order is fixed, hand-off chain, performance notes on signal_configuration.xml.
• references/usage-examples.md - ready-made input payload templates (schematic-parsing path, explicit-routings regression path, new-MCU/package, adding a peripheral on top of an existing set).
• references/worked-example.md - verified end-to-end run on S32K312MINI-EVB with the 23-row final routing table, the CAN0 skip and LIN1 -> LPUART5 re-route caveats, and the validation result.
• Related skills: s32ct-pins-info (enumeration), s32ct-generate-mex-config (template + patch), s32ct-pins-facade (validation), s32ct-peripherals-author-mex (natural next step), s32ct-clocks-info / s32ct-clocks-graft-mex (needed before driver code-gen), s32ct-generate-code (emit driver sources), s32ct-distributions (install-root discovery).