# NeoECU Target Architecture

NeoECU uses an AMP layout. The `CM7` side owns deterministic engine control; the secondary core is reserved for non-critical work and is outside the scope of this document.

This document describes the target `CM7` architecture. Current development-board details and temporary implementation notes live in [`DEVELOPMENT_SETUP.md`](./DEVELOPMENT_SETUP.md).

## CM7 Role

`CM7` is responsible for:

- capturing crank and cam timing edges with low jitter
- maintaining engine phase synchronization
- deriving the current four-stroke cycle position
- scheduling time-critical spark and injection transitions
- keeping interrupt paths short and deterministic

The engine-control path should stay small, explicit, and timer-driven.

## Runtime Flow

The target runtime model is:

1. A hardware timer captures crank and cam edges.
2. The input-capture callback stores each timestamp.
3. The callback wakes the task that owns that signal.
4. The task validates the event, updates engine state, and computes future actions.
5. Output-compare events apply scheduled actuator transitions.

Interrupt context owns timestamp capture and exact compare-time transitions. Task context owns filtering, state progression, synchronization, and scheduling decisions.

![CM7 control-flow graph](./img/arch.png)

## Sensors

### Crank

The crank signal is the primary timing source.

- One crank pulse represents `180` engine degrees.
- Consecutive crank intervals estimate current engine speed.
- Crank timing drives phase progression and scheduled outputs.

### Cam

The cam signal is the phase reference.

- One cam pulse represents the `720` degree four-stroke cycle.
- Cam timing is used to establish and recover cycle synchronization.
- Unexpected or missing cam events reduce or clear phase confidence.

## Shared State

The target model uses one compact shared engine state object. It contains:

- synchronization state
- crank cycle state
- cam event state
- cam miss tolerance
- recent crank and cam timestamp history
- scheduled spark state

State shared between ISR and task context must be explicit. If a value crosses that boundary, its ownership and meaning should be clear from the surrounding code.

## Synchronization

Synchronization has three states:

- `SYNC_NOT_OK`: phase is not trusted
- `SYNC_PENDING`: cam has been observed, but phase is not confirmed
- `SYNC_OK`: crank/cam relationship is trusted

Target progression:

1. Boot starts unsynchronized.
2. A cam event moves the system to pending sync.
3. The expected crank/cam phase relationship promotes sync to OK.
4. Missing or unexpected cam behavior drops sync back toward unknown phase.

When synchronized, crank pulses advance through:

1. `CYCLE_COMBUSTION`
2. `CYCLE_EXHAUST`
3. `CYCLE_INTAKE`
4. `CYCLE_COMPRESSION`

When unsynchronized, the crank state remains unknown until cam-assisted phase alignment restores confidence.

## Timing and Scheduling

Scheduled outputs are derived from recent crank timing.

The target scheduler should:

- compute future compare times from measured crank intervals
- arm hardware compare events instead of busy waiting
- keep actuator transitions in compare callbacks short and deterministic
- keep scheduling decisions near the sensor logic that drives them

Spark and injection should both follow this pattern:

1. The crank task computes the next transition time.
2. The timer compare channel is armed.
3. The compare callback applies the transition.
4. Follow-up transitions are scheduled by task logic.

## Core Modules

The intended `CM7` module boundaries are:

- `main.c`: boot, peripheral initialization, HAL callbacks, task creation
- `tasks/crank.c`: crank validation, cycle progression, output scheduling
- `tasks/cam.c`: cam validation and sync promotion
- `global_state.h`: shared state, enums, timing constants
- `ring_buffer.*`: timestamp history

## Open Target Work

The current target architecture still needs final decisions or validation for:

- complete injection scheduling
- final spark dwell-time handling
- production crank/cam phase validation
- sync-loss and recovery thresholds
- final hardware pin and timer routing