@h2loop/autosar 1.0.1 → 1.2.0

package/skills/autosar/references/codegen.md

@@ -0,0 +1,58 @@
+# Deterministic config code generation (`autosar_codegen`, `autosar_codegen_diff`)
+
+Generated C is never written by hand or by the model: run `autosar_codegen`, review with
+`autosar_codegen_diff`, then `autosar_build`. Same ECUC + param defs -> byte-identical files.
+
+## What is generated, from where
+| Output | Source |
+|---|---|
+| `<Mip>_Cfg.h` | pre-compile params of singleton containers as `<MIP>_<PARAM>` (booleans STD_ON/STD_OFF), `<MIP>_CFG_AR_RELEASE_*` (from the schema: AUTOSAR_00054 = R4.11.0), every symbolicNameValue param as `<Mip>Conf_<ContainerDef>_<Name>` (TPS_ECUC_02108) |
+| `<Mip>_Cfg.c` / `_Lcfg.c` / `_PBcfg.c` | one const table per multiplicity-n container def, placed by the most dynamic config class of its fields for the module's IMPLEMENTATION-CONFIG-VARIANT |
+| binding tables (e.g. `NvM_BlockDescriptorTable`, `PduR_Config`) | `codegen/bindings/*.json` (or `.hydron/codegen/bindings/`): the static code's struct layout, selected when its `detect` header is in the project |
+| `SchM_<Mip>.h` | exclusive areas the static code uses (`SchM_Enter_<Mip>_<EA>` found in non-generated C) + main functions |
+| `<Mip>_MemMap.h` | SWS_MemMap_00032 keyword file; pragmas from `codegen.memmap.pragmas` |
+
+Release macros: `<MIP>_CFG_AR_RELEASE_*` come from the static code's published information (`<MIP>_AR_RELEASE_*` in
+`<Mip>.h`, SWS_BSW_00059), so the generated release check matches the SIP; the ECUC schema release is the fallback.
+
+Handle IDs: missing symbolic values are assigned (lowest free >= def MIN, existing values kept, duplicates
+are errors) and written back into the ARXML in place (TPS_ECUC_02107); `write_back=false` keeps them in memory.
+
+A binding may declare `handleLayout` (e.g. Com: Tx signals/I-PDUs before Rx, because the static code indexes its
+tables by handle). Values that break it are renumbered and written back, only for withAuto params (ComHandleId,
+ComIPduHandleId); otherwise it is an error. Configuration the static code cannot represent (binding `require` /
+`unsupported`, e.g. BIG_ENDIAN signals or signal groups for the stand-in Com) fails generation; nothing is written.
+Notes list C code that uses a `<Mip>Conf_*` symbol the configuration no longer has (the build would fail on it).
+
+Output goes to `.hydron/codegen/out` unless `out_dir` is given (`project` = `codegen.outDir`, default `Output`).
+
+## Com
+`Com_Cfg.h`: ComGeneral switches, `COM_DEV_ERROR_DETECT` (ECUC_Com_00141), `ComConf_ComSignal_*`, `ComConf_ComIPdu_*`,
+`ComConf_ComIPduGroup_*` (and signal-group / group-signal) symbols. `Com_PBcfg.c` (binding): I-PDU buffers sized from the
+EcuC Pdu, signal tables (bit position, size, type, init value, transfer property, notification), Tx I-PDU table (PduR
+source handle via the shared EcuC Pdu, Tx mode, cycle = ComTxModeTimePeriod / ComMainTxTimeBase), Rx I-PDU table (deadline
+= smallest non-zero ComFirstTimeout/ComTimeout of its signals without update bit, SWS_Com_00291).
+Notification callouts: R25-11 Com users (ComUserModule -> ComUserModuleCnf, ComUserSignal with the same system signal,
+ComUserCallback of type COM_RX_ACK / COM_TX_ACK; `call:comUserCallback`), or, for a static Com with `void(void)`
+callbacks, the RTE's `Rte_COMCbk_<sn>()` / `Rte_COMCbkTAck_<sn>()` when the RTE's Rte_Cbk.h declares it
+(`call:rteSignalCallback`). Nothing is bound from guesses: no declaration, no callback.
+
+## Known differences from the sample/large fixture oracle (all explained)
+| Item | Oracle | Ours | Why |
+|---|---|---|---|
+| `NvM_BlockDescriptorTable[*].RamBlockDataAddress` | `X` | `&X` (as configured) | ECUC_NvM_00482 value is the address expression; kept verbatim, same address for arrays |
+| Rx I-PDU `TimeoutTicks` with mixed signal timeouts | largest ComTimeout | smallest non-zero | SWS_Com_00291 |
+| `<MIP>_CFG_*` version macros, generic ComGeneral/NvMCommon/... switches, Dem/Fee tables | absent | extra | def-driven output the oracle does not emit |
+| SchM main function names | `Com_MainFunctionTx` | same | SWS_Com says `Com_MainFunctionTx_<shortName>`; the instance named like its def keeps the SIP's legacy name |
+
+## Reading a diff
+- *missing*: in the reference only (e.g. a symbol whose ECUC container was deleted: stale Output, not a generator bug).
+- *extra*: generated only (generic def-driven macros/tables the reference generator does not emit).
+- *mismatch*: same name, different value. Typical causes: enum encoding (we use the def literal order unless the
+  binding maps it), the configured value verbatim (`&Ram` vs `Ram`).
+
+## MCAL
+Port/Dio come from the standard R25-11 defs. Register-level output needs a silicon mapping
+(`codegen.mcal.silicon`, e.g. `tc4d`) plus a project pin map (`codegen.mcal.pinMap`). The bundled TC4Dx file
+has public user-manual data only (status `skeleton`); its `needsVendorData` lists what Infineon's VSMD/BSWMD
+and MCAL static code must supply. Never invent register values.

package/skills/autosar/references/ecuc-model.md

@@ -15,7 +15,10 @@ its def through `DEFINITION-REF` (an AUTOSAR path); the `DEST` attribute names t
 
 **ECUC JSON** (what `ecuc_read` returns and `ecuc_edit add` accepts): containers keyed
 `"<DefName>:<ShortName>"` (just `"<Name>"` when equal), params by def short-name, multi-valued
-params as arrays, refs as `"->/path"`, `@path`/`@def`/`@at` metadata.
+params as arrays, refs as `"->/path"`, `@path`/`@def`/`@at` metadata (`@at` = the container's file:line).
+Each value is followed by `"@at:<Param>"` (file:line of its `VALUE`/`VALUE-REF` element — cite this one for a
+value) and integers by `"@hex:<Param>"` (plus `"@dec:<Param>"` when the ARXML text is hex). Keys starting with
+`@` are metadata; `ecuc_edit` ignores them.
 
 **Multiplicity.** `LOWER/UPPER-MULTIPLICITY` (or `UPPER-MULTIPLICITY-INFINITE`) on every container,
 param and ref def. Lower ≥ 1 = mandatory. A **choice container** (`ECUC-CHOICE-CONTAINER-DEF`)

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

@@ -23,10 +23,19 @@ Optional; pins what the tools load and how to generate/build:
   "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}
+  "build":     {"command": "make -C Build -j8 all", "timeoutSec": 3600},
+  "probe":     {"cc": "tricore-elf-gcc", "flags": ["-I", "SIP/include", "-DCPU=TC4D"]},
+  "checkGenerated": false,
+  "specDocs":  ["~/autosar/R25-11/txt/*.txt"]
 }
 ```
 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.
+
+`probe` sets the compiler/flags for the compile-only sizeof probe (H2L-NVM-001; default: the Makefile's CC/CFLAGS,
+else host `cc` with the discovered header dirs). `checkGenerated` turns the stale-Output check (H2L-GEN-001, run in a
+scratch copy) on/off; by default it is on when a `generate` command exists and the configuration is under 5 MB.
+`specDocs` (else `$AUTOSAR_SPEC_DOCS`, a path list) points `autosar_spec_id_check` at your own text exports
+(.txt/.md) of the AUTOSAR specifications; the pack bundles no spec text and no requirement-ID index.

package/skills/autosar/references/runnable-code.md

@@ -0,0 +1,50 @@
+# Runnable code: allowed RTE API, verify, context
+
+## Three tiers of an RTE API name (AUTOSAR CP R25-11 SWS_RTE 5.6)
+- **allowed** for runnable R: R has the access point the API's *Existence* requirement names. Only these may be
+  called from R and the functions it calls (SWS_Rte_CONSTR_09017/09083/...: "may only be used by the runnable that
+  contains the corresponding ..."). Shown in `autosar_build_context` section 3.
+- **generated**: some runnable of the SW-C is allowed it, so it is in `Rte_<Swc>.h`. Calling it from another runnable
+  compiles but is wrong (NOT-ALLOWED).
+- **derivable**: the port/element/IRV exists, but no runnable has the access point, so the API is not generated yet.
+
+| API | Access point (role) | Existence | Signature |
+|---|---|---|---|
+| `Rte_Write_<p>_<o>` / `Rte_Send_<p>_<o>` | dataSendPoint, data / queued element | SWS_Rte_01280 / 01281 | SWS_Rte_01071 / 01072 |
+| `Rte_Read_<p>_<o>` / `Rte_Receive_<p>_<o>` | dataReceivePointByArgument | SWS_Rte_01289 / 01288 | SWS_Rte_01091 / 01092 |
+| `Rte_DRead_<p>_<o>` | dataReceivePointByValue (primitive) | SWS_Rte_07395 | SWS_Rte_07394 |
+| `Rte_IRead[Ref]_<re>_<p>_<o>`, `Rte_IStatus_...` | dataReadAccess | SWS_Rte_01301 / 04578 / 02600 | SWS_Rte_03741 / 04577 / 02599 |
+| `Rte_IWrite[Ref]_<re>_<p>_<o>`, `Rte_IInvalidate_...` | dataWriteAccess | SWS_Rte_01302 / 05510 / 03801 | SWS_Rte_03744 / 05509 / 03800 |
+| `Rte_Call_<p>_<o>` / `Rte_Result_<p>_<o>` | (a)synchronousServerCallPoint / ...ResultPoint | SWS_Rte_01293/01294 / 01296 | SWS_Rte_01102 / 01111 |
+| `Rte_Mode_<p>_<o>` / `Rte_Switch_<p>_<o>` | modeAccessPoint / modeSwitchPoint | SWS_Rte_02629 / 02632 | SWS_Rte_02628 / 02631 |
+| `Rte_Prm_<p>_<o>` / `Rte_CData_<name>` | parameterAccess (port / local) | SWS_Rte_03929 / 01300 | SWS_Rte_03928 / 01252 |
+| `Rte_IrvRead/IrvWrite_<re>_<o>` | read/writtenLocalVariable, explicit IRV | SWS_Rte_01305 / 01306 | SWS_Rte_03560 / 03565 |
+| `Rte_IrvIRead/IrvIWrite[Ref]_<re>_<o>` | read/writtenLocalVariable, implicit IRV | SWS_Rte_01303 / 01304 | SWS_Rte_03550 / 03553 |
+| `Rte_Pim_<name>` | any runnable | SWS_Rte_01299 | SWS_Rte_01118 |
+| `Rte_Enter/Exit_<ea>` | canEnterExclusiveArea | SWS_Rte_01307 / 01308 | SWS_Rte_01120 / 01123 |
+
+Parameter passing: IN primitive by value (SWS_Rte_01017), IN struct/union by `const T*` (01018, 07086), IN array as
+pointer to the base type (05107); OUT always by pointer (01019, 07082, 05108); a struct/array return is a const
+pointer (07071, 07072). Multiple instantiation adds `Rte_Instance self` first. `Rte_IsUpdated`, `Rte_Invalidate`,
+`Rte_Feedback`, `Rte_IStatus` exist only with their ComSpec / InvalidationPolicy settings.
+
+## autosar_verify_rte
+Each `Rte_*` call is mapped to its enclosing function and to every runnable whose SYMBOL reaches it through the call
+graph (a static helper called from two runnables is checked for both). Statuses:
+- **OK**.
+- **NOT-ALLOWED**: rewrite with an allowed API, or add the access point to the runnable (ops given). For
+  `Rte_I*`/`Rte_Irv*` the runnable name is part of the API name: use the caller's.
+- **INVENTED**: no such port/element/runnable, or the wrong API kind for the port's direction or the element's
+  data/event semantics (the hint names the right one). When new data is truly needed the ops add the data
+  element (to the port's interface — note other users of that interface) or a new port + interface, then the access
+  point. New element types default to the type of a same-named element elsewhere, else `uint8` (flagged).
+After applying ops: `autosar_generate`, then verify again; then `autosar_build`. RTE lifecycle calls (`Rte_Start`, ...)
+in integration code are listed as not checked.
+
+## autosar_build_context
+Sections, in fixed order: 1 task, 2 SW-C definition, 3 allowed RTE API (exact header text), 4 runnable code,
+5 callees, 6 Com signals / NvM blocks behind its ports and calls, 7 FUZZY similar functions in other SW-Cs, 8 FUZZY
+similar past git changes (ARXML semantic delta + C hunks, ranked by overlap with the task's ports/elements/words and
+recency). Over budget (~4 chars/token): drop 8, drop 7, callees → prototypes, truncate code, truncate config,
+callees → names, code → head, compact 2. Sections 1 and 3 are never reduced. Output is byte-identical for the same
+inputs; the MANIFEST lists every source (file:line, sha1, included mode). Treat 7–8 as hints, never as truth.