@anik-2/autosar 0.0.0-stage → 0.1.1

package/skills/autosar/references/project-layout.md

@@ -0,0 +1,29 @@
+# Project layout (typical OEM / Tier-1 integration repo)
+
+| Folder | Holds | Who edits |
+|---|---|---|
+| `Config/` | ECUC values ARXML (one or more files per module), configurator project file | integrator, via the configurator or `ecuc_edit` |
+| `Input/` | System description / ECU extract, DBC/LDF/FIBEX, SWC descriptions, diagnostic data | comes from the OEM network/system team |
+| `Output/` | generated BSW/RTE/OS/MCAL configuration code and reports | generator only — never by hand |
+| `Source/` | in-house application and integration code (callouts, CDDs, SWC runnables) | developers |
+| `Build/` | makefiles/CMake, linker scripts, compiler options | build owner |
+| `SIP/` (or `BSW/`, `ThirdParty/`) | the vendor's Software Integration Package: static BSW code, BSWMD with vendor param defs (VSMD), generators | vendor; read-only |
+
+Names vary; the tools classify `.arxml` files by content, not by folder.
+
+## `.hydron/autosar.json`
+Optional; pins what the tools load and how to generate/build:
+
+```json
+{
+  "paramDefs": ["SIP/**/bswmd/*.arxml", "~/autosar/R22-11/AUTOSAR_MOD_ECUConfigurationParameters.arxml"],
+  "config":    ["Config/**/*.arxml"],
+  "input":     ["Input/**/*.arxml"],
+  "generate":  {"command": "<vendor-cli> -p Config/Ecu.dpa --generate {module}", "cwd": ".", "timeoutSec": 3600},
+  "build":     {"command": "make -C Build -j8 all", "timeoutSec": 3600}
+}
+```
+Without it: param defs = every `.arxml` holding `ECUC-MODULE-DEF` (else `$AUTOSAR_PARAMDEFS`, a
+path list), config = every file holding `ECUC-MODULE-CONFIGURATION-VALUES`, input = all other
+`.arxml`. Use the param defs of the release and vendor the project actually targets; the vendor
+BSWMD defs take precedence for vendor-specific parameters.

package/skills/autosar/references/symbolic-names.md

@@ -0,0 +1,25 @@
+# Symbolic names: how config becomes C symbols
+
+**TPS_ECUC_02108 (symbolic name rule).** For a container whose def has a parameter with
+`SYMBOLIC-NAME-VALUE=true` (typically the handle ID, e.g. `ComHandleId`, `PduRDestPduHandleId`,
+`CanIfTxPduId`), the generator emits a `#define` named
+
+    <Module>Conf_<ContainerDefName>_<ContainerShortName>   value = that parameter
+
+e.g. `ComConf_ComSignal_DoorLatch`, `PduRConf_PduRDestPdu_Tx_Msg1`. In-house code and other BSW
+modules must use these symbols, never literal IDs. A `*-REF` with `SYMBOLIC-NAME-REFERENCE` uses
+the target's symbolic name.
+
+**Consequences for edits.**
+- Renaming a container (SHORT-NAME) renames its symbol: every caller in `Source/` breaks. Run
+  `autosar_trace` on the element first to list callers.
+- Handle IDs: often zero-based and dense per module; shared IDs must agree across modules
+  (TPS_ECUC_02106). When adding a container with a handle ID, read the siblings and pick the next
+  free value per the module's convention; say which convention you assumed.
+- Vendor generators may add prefixes or use different names for vendor-specific containers;
+  `autosar_trace` reports links by `method` (`symbolic_name` = rule match, score 1.0;
+  `token_match`/`value_match` = heuristic, check the score).
+
+**Other generated artefacts.** Const configuration tables (`<Mod>_PBcfg.c`, `<Mod>_Lcfg.c`),
+`<Mod>_Cfg.h` macros (feature switches from booleans such as `…DevErrorDetect`), and callout
+prototypes from FUNCTION-NAME params (the in-house code must define those functions).

package/skills/autosar/references/workflow.md

@@ -0,0 +1,29 @@
+# The integration loop
+
+1. **Orient.** `ecuc_read` (no path) → modules, files, whether param defs loaded. If it warns that
+   no defs were found, stop and ask for the param-def location (or set `paramDefs`); without defs
+   nothing is validated and new elements cannot be added.
+2. **Understand the target.** `ecuc_read path=<container> schema=true` for the allowed params,
+   ranges, literals, multiplicity. For cross-module work also read the referenced containers
+   (e.g. ComIPdu → EcuC Pdu → PduR routing path → CanIf Tx PDU). `autosar_trace` shows which C
+   symbols and callers depend on the element.
+3. **Edit.** One `ecuc_edit` call with all related ops (it is all-or-nothing). Use `dry_run` to
+   show a non-trivial change first. Never write ARXML yourself.
+4. **Validate.** `ecuc_validate` (scope with `module`/`files` on big projects). Separate findings you
+   introduced from pre-existing ones (`arxml_diff` against the committed version helps). Fix yours.
+5. **Generate.** `autosar_generate` (only with no new errors). If it fails, read its error output,
+   map each message to the AUTOSAR path / parameter, fix via `ecuc_edit`, re-validate.
+6. **Review output.** `arxml_diff` for ARXML outputs; for C, check the expected symbols changed
+   (e.g. a new `ComConf_ComSignal_<Name>`).
+7. **Build.** `autosar_build`; compile/link errors usually mean a renamed/removed symbolic name or a
+   callout (FUNCTION-NAME) not implemented in `Source/`. `autosar_trace` the symbol to its config.
+8. **Report.** List each change as `path` (DEFINITION-REF) old → new, its config class, the
+   validation result, generator/build status, and impacted callers.
+
+## Failure handling
+- ECUC-UNKNOWN-DEF everywhere → wrong release/vendor defs loaded; check `paramDefs`.
+- ECUC-REF-UNRESOLVED → the System/SWC ARXML is not in `input`; add it rather than ignoring.
+- `ecuc_edit` rejected a value → it violates the def; do not `force` unless the user confirms the
+  def is wrong for their vendor release, and say so.
+- Backend tools (`autosar_trace`, `autosar_config_lookup`) report NOTES such as "data source
+  predates the feature, re-ingest it": relay them; the graph needs a re-ingest of the code data source.