autonomousguy 0.6.4

package/skills/autosar/autosar-bsw/references/adaptive-ap.md

@@ -0,0 +1,104 @@
+# Adaptive AUTOSAR (AP) variant - platform services and communication
+
+Use this when the input names Adaptive AUTOSAR (AP): ara::com, ara::exec, ara::diag, ara::per, C++14+, POSIX/Linux/QNX, service-oriented (SOA), manifests, Execution Management, or State Management.
+
+AP has no BSW layer and no COM stack. The Classic BSW concerns map onto ara:: Functional Clusters provided by the Adaptive Platform Foundation and Services. Communication is service-oriented over SOME/IP or DDS, not signal-based over CAN PDUs. Configuration is by JSON/ARXML manifests deployed per machine and per executable, not by static EB Tresos / DaVinci ECU config.
+
+## Classic-to-Adaptive mapping
+
+| Classic concern | Adaptive equivalent | Notes |
+|---|---|---|
+| Com / PduR (signals, I-PDUs) | ara::com (services, events, methods, fields) | proxy on consumer, skeleton on provider; service discovery; transport binding SOME/IP or DDS |
+| Dcm / Dem (UDS, DTCs) | ara::diag | diagnostic server, DTCs, operation/monitor, ara::diag::DTCInformation |
+| NvM / MemIf / Fee (persistence) | ara::per | key-value storage and file storage, redundancy/CRC via per config |
+| Os (tasks, schedule, ExclusiveArea) | ara::exec + POSIX scheduling | Execution Management starts/stops processes; State/Function-Group state; threads, not OS tasks |
+| Wdg (watchdog) | ara::phm (Platform Health Management) | supervised entities, alive/deadline/logical supervision |
+| Det / Dlt | ara::log | severity-leveled logging, not DET hooks |
+
+## Modes (AP)
+
+### Service configuration (replaces BSW configuration)
+
+1. Identify the service interface(s): events, methods, fields. Define in the service interface description (ARXML) and the deployment manifest (SOME/IP service ID, instance ID, event/method IDs).
+2. Decide transport binding: SOME/IP (signal-based service binding, service discovery on UDP) or DDS.
+3. Provider: implement the skeleton, OfferService(), set fields, Send() events. Consumer: FindService() / StartFindService(), create the proxy, Subscribe() to events, call methods (returning ara::core::Future).
+4. Persistence: declare ara::per key-value or file storage in the manifest; access via OpenKeyValueStorage / OpenFileStorage.
+5. Diagnostics: configure ara::diag DTCs and the diagnostic server manifest; map monitors to events.
+6. Produce a manifest checklist and flag common deployment errors (mismatched service/instance IDs, missing service discovery, machine vs executable manifest scope).
+
+### Manifest debugging (replaces ARXML debugging)
+
+1. Classify the error: service/instance ID mismatch between provider and consumer manifests; missing required-port to provided-port binding; network endpoint (IP/port) wrong; transport binding mismatch (SOME/IP vs DDS); data type mismatch in the service interface.
+2. Locate it in the right manifest scope: Machine Manifest (machine-wide, network, ara::com transport), Execution Manifest (per process, startup, state dependency), Service Instance Manifest (service-to-instance mapping).
+3. Provide the corrected manifest fragment and a prevention rule.
+
+### Startup / execution troubleshooting (replaces RTE generation troubleshooting)
+
+There is no RTE generation in AP. The analogous failures are Execution Management and binding failures:
+1. Process does not start: Execution Manifest startup config, dependency on a Function-Group state not reached, missing resource/permission.
+2. Service not discovered: service discovery not running, service/instance ID mismatch, network down, firewall/multicast for SOME/IP-SD.
+3. Method call hangs or throws: ara::core::Future timeout, skeleton not offering, ara::com error (kServiceNotAvailable). Inspect the ara::com::ErrorCode.
+4. Give the exact manifest field or ara::com call to fix and a post-fix validation step.
+
+### Service communication debugging (replaces COM stack debugging)
+
+1. Classify symptom: event not received (subscription, offer, discovery), wrong value (serialization / data type / endianness in SOME/IP), intermittent (network loss, QoS), method error (Future error code).
+2. Confirm network level first: capture SOME/IP or DDS traffic (Wireshark with the SOME/IP dissector, or DDS spy). Check service discovery (Offer/Subscribe/SubscribeAck) before blaming the application.
+3. Walk the path: provider skeleton Offer/Send -> transport (SOME/IP-SD + serialization) -> consumer proxy Subscribe + event receive handler. This replaces the CanIf -> PduR -> Com layer-walk.
+4. Probe with ara::log at each stage; inspect ara::core::Result / ErrorCode rather than DET hooks.
+5. Common anti-patterns: service/instance ID mismatch; consumer subscribes before provider offers and never retries; serialization config mismatch (alignment, endianness, struct order) between provider and consumer; QoS/reliability mismatch in DDS.
+
+## Output format (AP)
+
+Begin with `Platform: Adaptive (AP)`. Then use the matching layout:
+
+### Service configuration
+```
+## Service Configuration: <Service/Interface>
+
+### Service Interface
+[events / methods / fields, with SOME/IP or DDS binding]
+
+### Deployment Manifest
+| Manifest | Field | Value | Notes |
+|----------|-------|-------|-------|
+
+### Provider / Consumer Steps
+[skeleton Offer + Send ; proxy Find + Subscribe + call]
+
+### Common Errors & Resolutions
+| Error | Root Cause | Fix |
+
+### Validation Checklist
+- [ ] ...
+```
+
+### Manifest debug / startup / communication
+```
+## AP Debug Report
+
+### Classification
+[event-not-received | wrong-value | method-error | startup | manifest-mismatch]
+
+### Network/Discovery Confirmation
+[SOME/IP-SD or DDS capture - service offered? subscribed? acked?]
+
+### Path Walk
+| Stage | Check | Expected | Observed / Next Probe |
+|-------|-------|----------|------------------------|
+| Provider skeleton | Offer/Send | ... | ... |
+| Transport (SOME/IP/DDS) | discovery + serialization | ... | ... |
+| Consumer proxy | Subscribe + handler | ... | ... |
+
+### Most Likely Root Cause
+[manifest field or ara:: call + one-sentence why]
+
+### Fix
+[corrected manifest fragment or ara:: code change]
+
+### Safety Impact
+[None / ASIL-X - re-verification scope]
+
+### Prevention Rule
+[one line]
+```

package/skills/autosar/autosar-bsw/references/boot-nvm-power.md

@@ -0,0 +1,127 @@
+# Boot, NVM & power - reference
+
+Depth for the **Boot, NVM & power** mode of the AUTOSAR BSW skill. Classic AUTOSAR (CP) focus.
+ASCII only, no em dashes. Consult the relevant sub-area; do not load the whole file unless needed.
+
+---
+
+## 1. Boot / startup
+
+### 1a. Bare-metal startup
+
+Reset vector -> startup code -> C runtime -> `main`:
+
+1. Reset vector points to the startup routine (often `Reset_Handler`).
+2. Set the initial stack pointer; configure the clock tree (PLL, flash wait states) so the rest of
+   init runs at the intended frequency.
+3. Copy initialised data (`.data`) from flash to RAM; zero the `.bss` section.
+4. Run C++ static constructors if any (`.init_array`).
+5. Call `main` (or the AUTOSAR `EcuM_Init` path).
+
+Common faults: `.bss` not zeroed (random initial state), `.data` copy skipped (initialised globals
+read as garbage), wrong startup file for the silicon variant, vector table not at the address the
+core expects (VTOR misconfigured).
+
+### 1b. Classic AUTOSAR startup (EcuM / BswM)
+
+Phase order:
+
+- `EcuM_Init` -> `StartPreOS` sequence: init MCU/MCAL drivers needed before the OS (Mcu, Port, Dio,
+  Gpt, Wdg + WdgM init, BSW scheduler basics).
+- `StartOS` (the OS starts, tasks begin scheduling).
+- `StartPostOS` sequence: `NvM_ReadAll`, communication stack init (CanIf, Com, PduR, ComM, Nm),
+  Dem/Dcm init, then RTE start and SWC init runnables.
+
+Driver init order must follow the dependency chain MCAL -> ECU abstraction -> BSW services -> RTE ->
+SWC. A module initialised out of order (e.g. Com before its PDU config, or a SWC reading NvM data
+before `NvM_ReadAll` finished) is the usual root cause of startup defects.
+
+BswM arbitrates modes from rules (condition -> action list). It coordinates startup, wakeup,
+shutdown, and partial networking actions.
+
+### 1c. Bootloader and reprogramming (UDS flash download)
+
+Typical UDS sequence for a flash update (ISO 14229 + ISO 15765 transport):
+
+1. `0x10 02` - switch to programming session (often via `0x10 03` extended first).
+2. `0x27` - security access (request seed, send computed key).
+3. `0x31` - RoutineControl: erase memory / check programming preconditions.
+4. `0x34` - RequestDownload (memory address + size, compression/encryption format).
+5. `0x36` - TransferData (repeated blocks, block sequence counter).
+6. `0x37` - RequestTransferExit.
+7. `0x31` - RoutineControl: check memory / verify checksum or signature.
+8. `0x11 01` - ECU reset; jump to the new application.
+
+Design points:
+- Dual-bank / A-B layout lets the old image stay valid until the new one is verified.
+- An application-validity marker (and CRC or signature over the app) gates the bootloader's
+  jump-to-application decision; never jump to an unverified image.
+- Keep the bootloader minimal and independently updatable only with great care (a bricked
+  bootloader is unrecoverable in the field).
+
+---
+
+## 2. NVM storage stack
+
+### 2a. NvM block descriptor options
+
+- `NvMBlockManagementType`: `NVM_BLOCK_NATIVE` (one copy), `NVM_BLOCK_REDUNDANT` (two copies, survives
+  one corrupted instance), `NVM_BLOCK_DATASET` (indexed set, e.g. per-variant calibration).
+- CRC: `NvMBlockUseCrc` + `NvMCrcType` (CRC16/CRC32) detects torn or corrupted writes on read.
+- Write policy: immediate (`NvM_WriteBlock` flushed promptly) vs deferred (queued, flushed by
+  `NvM_WriteAll` or the main function). Deferred trades latency for throughput - the source of many
+  "lost after power cut" bugs.
+- `NvMWriteBlockOnce`: TRUE for write-once data (e.g. end-of-line VIN); FALSE for values that change.
+- `NvMSelectBlockForWriteAll`: TRUE to include the block in the `NvM_WriteAll` sweep.
+- Default value: applied on first-ever init (or after a failed CRC with no redundant copy).
+
+### 2b. Fee / Ea over MemIf
+
+NvM does not touch flash directly. It goes NvM -> MemIf -> Fee (flash EEPROM emulation) or Ea
+(EEPROM abstraction) -> the flash/EEPROM driver. Fee/Ea manage logical blocks over physical
+sectors, including sector switching when a sector fills.
+
+### 2c. Wear leveling
+
+Flash sectors have a finite erase-cycle budget. Strategies: rotate writes across sectors, coalesce
+writes (avoid writing unchanged blocks), and budget the erase count against vehicle lifetime
+(e.g. N writes/day x 15 years must stay under the endurance rating with margin). Watch write
+amplification - a small logical write can trigger a full sector erase + copy.
+
+### 2d. Sequencing
+
+- Startup: `NvM_ReadAll` populates RAM mirrors; consumers must wait for completion.
+- Runtime: `NvM_WriteBlock` (single) / `NvM_MainFunction` services the job queue.
+- Shutdown: `NvM_WriteAll` flushes all selected blocks; poll `NvM_GetStatus() == NVM_IDLE` or use
+  the job-end notification before cutting power.
+
+---
+
+## 3. Power / state management
+
+### 3a. EcuM sleep / wakeup state machine
+
+`RUN` -> (GoSleep requested) -> run shutdown/sleep prep (including `NvM_WriteAll`) -> `SLEEP`
+(MCU low-power, selected wakeup sources armed) -> wakeup event -> wakeup validation -> back to `RUN`.
+
+Wakeup sources (CAN, LIN, local pin, timer) must be configured and validated; a spurious wakeup
+that fails validation should return the ECU to sleep rather than fully starting up.
+
+### 3b. Partial networking (PN)
+
+Partial Network Clusters (PNC) let parts of the network sleep while others stay awake. A
+PN-capable CAN transceiver wakes only on a configured wakeup frame. ComM and Nm coordinate which
+PNCs are active; the transceiver stays in a selective wake mode otherwise. Saves quiescent current.
+
+### 3c. Ordered shutdown
+
+BswM runs a shutdown action list. The critical ordering rule: complete `NvM_WriteAll` (and confirm
+`NVM_IDLE`) BEFORE commanding the transceiver to Sleep and the MCU to low-power. If sleep is entered
+while deferred NvM jobs are still queued, the data is lost on power-down. Confirm worst-case
+WriteAll time fits the board hold-up time after ignition-off.
+
+### 3d. Low-power MCU modes
+
+SLEEP / STOP / STANDBY (names vary by silicon) trade wake latency and retained state against
+current draw. Combine with clock gating and peripheral power-down. Verify which RAM/registers are
+retained in the chosen mode so post-wake state is correct.

package/skills/autosar/autosar-bsw/references/com-stack.md

@@ -0,0 +1,118 @@
+# AUTOSAR COM Stack — Layer-by-Layer Reference
+
+Comprehensive reference for debugging the AUTOSAR Classic COM stack (CanDrv → CanIf → PduR → Com → RTE → SWC), TX and RX directions. Use alongside the SKILL.md COM-stack mode for fast layer-walk lookups.
+
+## RX path (top-down from bus to SWC)
+
+```
+Can_Hw                            (hardware FIFO / mailbox)
+  → Can_RxIndication              (CanDrv ISR)
+  → CanIf_RxIndication            (CanIf RX dispatch)
+  → PduR_CanIfRxIndication        (PduR routing)
+  → Com_RxIndication              (Com signal unpack)
+  → Rte_Write_*                   (RTE to SWC)
+```
+
+### Layer responsibilities
+
+| Layer  | Owns                                                         | EB Tresos containers                          |
+|--------|--------------------------------------------------------------|-----------------------------------------------|
+| CanDrv | Hardware filters, mailbox config, baudrate, controller state | `CanHardwareObject`, `CanController`          |
+| CanIf  | PDU dispatching, user upper-layer routing                    | `CanIfRxPduCfg`, `CanIfTxPduCfg`, `CanIfRxPduCanIdMask` |
+| PduR   | Routing table (CanIf ↔ Com / TP)                             | `PduRRoutingPath`, `PduRSrcPdu`, `PduRDestPdu` |
+| Com    | Signal pack/unpack, scaling, init, timeout                   | `ComIPdu`, `ComSignal`, `ComTimeoutNotification` |
+
+## TX path (top-down from SWC to bus)
+
+```
+Rte_Write_*                       (SWC)
+  → Com_SendSignal                (Com signal pack)
+  → Com_TriggerIPduSend            (Com → PduR)
+  → PduR_ComTransmit              (PduR routing)
+  → CanIf_Transmit                (CanIf → hw)
+  → Can_Write                     (CanDrv)
+  → Can_Hw                        (hardware mailbox / FIFO)
+```
+
+## Symptom → first layer to suspect
+
+| Symptom                                                  | First suspect       |
+|----------------------------------------------------------|---------------------|
+| No signal at all (always init value)                     | CanDrv (filters, controller state) |
+| Wrong value (constant, but wrong)                        | Com (byte order, scaling, start bit) |
+| Sometimes correct, sometimes init                        | CanIf RX buffer overflow / Com main-function task overrun |
+| Correct after ignition cycle, then drifts to init        | Com `ComTimeout` firing |
+| Signal in CAN trace but SWC sees init                    | CanIf filter / PduR routing |
+| SWC writes, nothing on bus (TX)                          | `Com_SendSignal` return + `Com_MainFunctionTx` |
+| TX intermittent                                          | `ComTxModeMode`, `ComMinimumDelayTime`, CanIf mailbox congestion |
+
+## RX layer-walk checklist (when frame IS on bus but SWC sees nothing)
+
+### CanDrv
+- Controller `CAN_CS_STARTED`? `CanIf_GetControllerMode`.
+- Hardware filter mask: `CanHardwareObject` → `CanHwObjectCount`, `CanIdValue`, `CanIdMask`. **Common bug**: mask requires bits the actual ID doesn't have.
+- `Can_MainFunction_Read` actually being called? Default 1 ms; if its OS task is overrun or disabled, RX frames sit in the mailbox until overwritten.
+
+### CanIf
+- `CanIfRxPduCfg`: entry exists for this CAN ID + Controller + HRH?
+- `CanIfRxPduCanIdMask` / `CanIfRxPduCanIdRange`: runtime CAN ID matches?
+- `CanIfUserRxIndicationUL` must be `PDUR` (not `CDD` or `NONE`).
+- If `CanIfPublicReadRxPduDataApi` is enabled and PduR uses polled read, confirm PduR is calling `CanIf_ReadRxPduData`.
+
+### PduR
+- `PduRRoutingPath` for this Rx PDU has destination `PDUR_COM`.
+- `PduRSrcPdu` references the CanIf Rx PDU; `PduRDestPdu` references the Com Rx PDU.
+- If routing is to a TP module instead (CanTp / FrTp), the frame won't reach Com.
+
+### Com
+- `ComIPdu` exists for the routed PDU; `ComIPduDirection = RECEIVE`.
+- `ComSignal`: `ComBitPosition`, `ComBitSize`, `ComSignalEndianness` (`BIG_ENDIAN` / `LITTLE_ENDIAN` — must match DBC `@1+` vs `@0+`), `ComSignalType`, `ComInitValue`.
+- `ComNotification` callback fires? Add a counter. If yes, problem is downstream (RTE/SWC). If no, upstream.
+- `ComTimeoutNotification` / `ComFirstTimeout`: confirm timeout isn't triggering before first valid frame, replacing the value with `ComInitValue`.
+
+## TX layer-walk checklist (when SWC writes but bus shows nothing)
+
+### SWC / RTE
+- Did the SWC actually call `Rte_Write_*`? Check return code.
+- Confirm `Com_SendSignal` was reached (DET, breakpoint, callout).
+
+### Com
+- `ComIPdu` `ComIPduDirection = SEND`.
+- `ComTxModeMode`: `PERIODIC`, `DIRECT`, or `MIXED`.
+  - `DIRECT` requires `ComTxModeNumberOfRepetitions ≥ 1` after `Com_SendSignal`.
+  - `PERIODIC` requires `Com_MainFunctionTx` to be running.
+- `ComMinimumDelayTime`: two `Com_SendSignal` calls within this window are merged.
+- `ComTxIPduUnusedAreasDefault`: non-zero defaults can corrupt unused bits.
+
+### PduR
+- `PduRRoutingPath` exists for the Com Tx PDU with destination `PDUR_CANIF`.
+
+### CanIf
+- `CanIfTxPduCfg` exists, references correct `CanHardwareObject` (HTH).
+- `CanIfTxPduUserTxConfirmationUL = PDUR` so the confirmation closes the Com loop.
+- Mailbox congestion: if `Can_Write` returns `CAN_BUSY` and the BSW retry strategy isn't configured, transmissions silently drop.
+
+### CanDrv
+- Bus-off state (`CanIf_GetControllerMode` → `CANIF_CS_STOPPED` indicates bus-off recovery).
+- Controller not started, baudrate mismatch.
+
+## Probe / instrumentation patterns
+
+- DET hooks: enable `CANIF_DEV_ERROR_DETECT` and `COM_DEV_ERROR_DETECT`; route `Det_ReportError` to a trace buffer.
+- Counters in `ComNotification`, `CanIf_RxIndication` user callback.
+- For RX: temporarily map the signal to a debug output port or NvM trace block.
+- For TX: capture the bus with the same CAN tool that proved the frame was missing.
+
+## Common configuration anti-patterns
+
+- CanIf Rx PDU uses a CAN ID mask that excludes the runtime ID (0x1FFFFFFF mask applied to an 11-bit ID, or vice versa).
+- Com `ComSignalEndianness` mismatched with DBC: `@1+` is `LITTLE_ENDIAN` (Intel), `@0+` is `BIG_ENDIAN` (Motorola).
+- `ComBitPosition` interpreted differently by sender and receiver — the DBC tool and AUTOSAR generator may number bits in opposite directions for Motorola signals.
+- `Com_MainFunctionRx` and `Com_MainFunctionTx` mapped to different OS tasks with different priorities — starvation risk.
+- `ComFilterAlgorithm` other than `ALWAYS` silently dropping values that don't match the filter (`MASKED_NEW_DIFFERS_X` is the classic gotcha).
+
+## Bus-level pre-check (always step 1)
+
+Never debug the stack before confirming what's on the wire:
+- **RX**: capture with CANalyzer / BusMaster / candump / PCAN-View. Confirm expected CAN ID, DLC matches PDU length, cycle time within tolerance.
+- **TX**: same capture. If your ECU should be transmitting and the frame isn't on the bus, before debugging the stack confirm hardware: bus terminated (60 Ω), transceiver not in Sleep, CAN_H/CAN_L not swapped, no bus-off state.

package/skills/autosar/autosar-bsw/references/comms-protocol.md

@@ -0,0 +1,130 @@
+# Communication protocol - reference
+
+Depth for the **Communication protocol** mode of the AUTOSAR BSW skill. Classic AUTOSAR (CP) focus,
+with SOME/IP and DoIP that also appear on Adaptive. ASCII only, no em dashes. Consult the relevant
+sub-area; do not load the whole file unless needed.
+
+---
+
+## 1. On-board buses
+
+### 1a. CAN and CAN FD
+
+Frame and signal layout:
+- A signal is defined by start bit, bit length, byte order, factor, offset, and value range.
+- Byte order: DBC `@1+` = Intel / little-endian, `@0+` = Motorola / big-endian. AUTOSAR Com
+  `ComSignalEndianness` must match the DBC, and `ComBitPosition` follows the AUTOSAR convention
+  (which differs from DBC start-bit numbering for Motorola signals - a frequent defect).
+- Classic CAN: up to 8 data bytes, DLC 0..8.
+- CAN FD: payload up to 64 bytes; DLC values 9..15 map to lengths 12,16,20,24,32,48,64. Bit Rate
+  Switch (BRS) raises the data-phase bit rate; the arbitration phase stays at the nominal rate.
+- Transmit modes: cyclic (fixed period), on-change (event), or mixed (cyclic + on-change).
+- E2E protection (counter + CRC, AUTOSAR E2E profiles) for safety-relevant signals: the receiver
+  checks the counter sequence and CRC and applies a timeout/fault reaction.
+
+### 1b. LIN
+
+- Schedule table: the master runs frame slots on a fixed schedule; each slot is a frame header the
+  master sends, with a configured slot delay.
+- Master/slave: the master sends the header; a configured responder (master or a slave) sends the
+  response bytes.
+- Checksum: classic (data only) vs enhanced (data + PID); both ends must agree.
+- Response timeout and the LIN error handling (no-response, checksum error, framing) feed the LIN
+  status and any diagnostic reaction.
+
+---
+
+## 2. Transport and routing
+
+### 2a. CanTp (ISO 15765-2) segmentation
+
+For payloads larger than a single frame (> 7 data bytes classic, > 63 CAN FD, accounting for the
+PCI byte):
+- Single Frame (SF) for short messages.
+- First Frame (FF) starts a multi-frame message and declares total length.
+- Flow Control (FC) from the receiver: ClearToSend / Wait / Overflow, plus Block Size (BS = frames
+  between FCs) and STmin (minimum separation time between consecutive frames).
+- Consecutive Frames (CF) carry the remaining data with a rolling sequence number.
+- Timeouts: N_As / N_Ar (sender/receiver frame transmission), N_Bs (wait for FC), N_Cr (wait for
+  CF). A timeout aborts the segmented transfer.
+
+### 2b. PduR routing
+
+- Routing path types: signal routing, PDU (I-PDU) routing, and TP routing for segmented data.
+- Gateway routing forwards PDUs between channels (e.g. CAN to CAN, CAN to Ethernet) with optional
+  gateway-on-the-fly for large TP messages.
+- PduR also routes between the bus interface and upper layers (Com, Dcm) - a missing routing path
+  is a common reason a frame is on the bus but never reaches the SWC or the diagnostic stack.
+
+---
+
+## 3. Network management (ComM / Nm) and partial networking
+
+- ComM: channels and users. A user requests FULL_COMMUNICATION or NO_COMMUNICATION; ComM aggregates
+  requests per channel and asks Nm to keep the bus awake or release it.
+- Nm coordinated state machine: Repeat Message State -> Normal Operation State -> Ready Sleep State
+  -> Bus Sleep State. Nm messages keep all nodes awake together and coordinate a synchronized sleep
+  so no node is left talking to a sleeping bus.
+- Partial Networking (PN): Partial Network Clusters (PNC) allow subsets of the network to sleep
+  while others run. A PN-capable transceiver wakes only on a configured wakeup frame. See the power
+  handling in `boot-nvm-power.md` for the transceiver/EcuM side.
+
+---
+
+## 4. Diagnostics over the bus (UDS / Dcm / Dem)
+
+### 4a. UDS service handler - NRC check order
+
+Validate every request in this order and return the first failing NRC:
+1. message length -> NRC 0x13 (incorrectMessageLengthOrInvalidFormat)
+2. service supported -> NRC 0x11 (serviceNotSupported)
+3. sub-function supported -> NRC 0x12 (subFunctionNotSupported), or 0x7E in active session
+4. session valid -> NRC 0x7F (serviceNotSupportedInActiveSession)
+5. security unlocked -> NRC 0x33 (securityAccessDenied)
+6. request in range -> NRC 0x31 (requestOutOfRange)
+7. conditions correct -> NRC 0x22 (conditionsNotCorrect)
+On success, the positive response SID is request SID + 0x40.
+
+Common services: 0x10 (session control), 0x11 (ECU reset), 0x14/0x19 (clear/read DTC), 0x22/0x2E
+(read/write DID), 0x27 (security access), 0x28 (communication control), 0x2F (IO control), 0x31
+(routine control), 0x34-0x37 (download/transfer), 0x3E (tester present), 0x85 (control DTC setting).
+
+In AUTOSAR these are implemented as Dcm callouts; Dcm handles session/security/response framing and
+pending (0x78) responses for async operations. Do not parse UDS outside the Dcm framework.
+
+### 4b. DTC status byte (ISO 14229-1)
+
+Bit 0 testFailed, bit 1 testFailedThisOperationCycle, bit 2 pendingDTC, bit 3 confirmedDTC,
+bit 4 testNotCompletedSinceLastClear, bit 5 testFailedSinceLastClear,
+bit 6 testNotCompletedThisOperationCycle, bit 7 warningIndicatorRequested (MIL).
+Never manipulate these bits directly. Report faults via Dem (`Dem_SetEventStatus` /
+`Dem_ReportErrorStatus`); Dem manages the transitions per the configured debounce, operation
+cycles, and aging. (Dcm/Dem configuration is in the BSW configuration mode.)
+
+---
+
+## 5. Service-oriented Ethernet
+
+### 5a. SOME/IP
+
+Message format fields: Message ID (Service ID + Method/Event ID), Length, Request ID (Client ID +
+Session ID), Protocol Version, Interface Version, Message Type (REQUEST, REQUEST_NO_RETURN,
+NOTIFICATION, RESPONSE, ERROR), Return Code. Serialization packs parameters per the service
+interface, big-endian by default, with configured alignment and length fields for dynamic data.
+
+Service Discovery (SOME/IP-SD):
+- Provider sends OfferService (service + instance + endpoint, with a TTL).
+- Consumer sends FindService (optional) and SubscribeEventgroup (eventgroup + its own endpoint).
+- Provider replies SubscribeEventgroupAck (or Nack). Only then are eventgroup events delivered.
+- Events are delivered unicast or multicast; multicast requires the consumer to join the group.
+- TTL must be renewed; TTL 0 means stop offering/subscribing.
+
+### 5b. DoIP (ISO 13400)
+
+- Vehicle announcement / VehicleIdentificationRequest-Response to discover the ECU on IP.
+- Routing activation handshake: RoutingActivationRequest (source address, activation type) ->
+  RoutingActivationResponse (response code, logical addresses). UDS diagnostics only flow after a
+  successful activation.
+- UDS is then tunneled in DoIP diagnostic messages (with source/target logical addresses) over TCP.
+- On Classic this rides SoAd plus the SOME/IP / DoIP modules; on Adaptive the equivalent service
+  communication is provided by ara::com - state which platform applies.