# Church Machine — Efinix Ti60 F225  SoC+CM Build Package

## What's Inside

This package contains the **Sapphire RISC-V SoC + Church Machine (ECO-001B)**
combined source for the Efinix Ti60F225 development board.
Everything needed to rebuild from source is included — no extra downloads required.

### Files
- `church_soc_cm.xml`         — Efinity project — **open this in Efinity IDE**
- `sapphire.v`                — Efinix Sapphire SoC IP (RISC-V SoC RTL)
- `sapphire_define.vh`        — Efinix Sapphire SoC defines
- `church_ti60_f225.v`        — Church Machine RTL (ECO-001B, Amaranth/Yosys)
- `top.v`                     — Top-level SoC+CM wrapper
- `apb3_cm_bridge.v`          — APB3 register bridge (Sapphire SoC ↔ Church Machine)
- `church_soc_cm.sdc`         — Timing constraints
- `church_soc_cm.peri.xml`    — Periphery I/O pin assignments
- `firmware/`                 — Sapphire RISC-V firmware (main.c, crt0.S, Makefile)
- `run_efx_map.sh`            — Synthesis (strips EFX-0002 banned params, calls efx_map)
- `run_efx_pnr.sh`            — Place & Route
- `run_efx_pgm.sh`            — Bitstream generation
- `Makefile`                  — `make bitstream` runs all 6 steps in order
- `BUILD_SOC_CM.md`           — Authoritative step-by-step build guide
- `local_bridge.py`           — Serial bridge to connect the board to the IDE
- `bridge.sh`                 — Auto-detects port and launches local_bridge.py
- `outflow/church_soc_cm.hex` — **Pre-built bitstream** (flash immediately, no toolchain)

## Case 1 — Flash the pre-built bitstream (no toolchain needed)

The official SoC+CM bitstream is at `outflow/church_soc_cm.hex`.

```bash
sudo ~/oss-cad-suite/bin/openFPGALoader \\
  -b titanium_ti60_f225_jtag \\
  -f outflow/church_soc_cm.hex
```

Or via Efinity IDE: **Tool → Programmer** → JTAG → load `outflow/church_soc_cm.hex` → Program.

On boot the board sends two serial streams:
- **ttyUSB2** (57600 baud): `CHURCH Ti60 SoC+CM v2.0\r\n`  ← Sapphire SoC greeting + call-home
- **ttyUSB3** (115200 baud): NIA trace + CALLHOME JSON packets ← Church Machine

Connect to the IDE:
```bash
./bridge.sh --ide=http://localhost:5000
```

---

## Case 2 — Synthesise from Efinity IDE (RISC-V toolchain required)

`sapphire.v` in this package has placeholder BRAM initialisation (all zeros) so
that Efinity IDE can open the project immediately.  To produce a bitstream with
real firmware you must patch `sapphire.v` first — one terminal command:

```bash
bash prep_ide_synthesis.sh
```

This compiles the RISC-V firmware (`~/efinity/efinity-riscv-ide-2025.2/`) and
embeds the resulting bytes into `sapphire.v`.  After it finishes, click
**Run Synthesis** in Efinity IDE as normal.

> If you see **no USB2 messages** after flashing, your bitstream was built
> without running `prep_ide_synthesis.sh` first — the Sapphire RISC-V core
> is executing zero firmware.  Re-run `prep_ide_synthesis.sh`, re-synthesise,
> and reflash.  Or just use Case 1 (pre-built hex already has real firmware).

---

## Case 3 — Full command-line rebuild (Efinity 2026.1 + RISC-V toolchain)

```bash
make bitstream
```

Runs all 6 steps automatically (firmware → BRAM patch → synth → PnR → hex).
Output: `outflow/church_soc_cm.hex` and `outflow/church_soc_cm.bit`

Full step-by-step guide and troubleshooting: **`BUILD_SOC_CM.md`**

### Flash

```bash
sudo ~/oss-cad-suite/bin/openFPGALoader \\
  -b titanium_ti60_f225_jtag \\
  -f outflow/church_soc_cm.hex
```

---

## Resource Usage

- ~24%% of Ti60F225 logic (SoC + Church Machine core + APB3 bridge)
- `win_mem` (16 KB) and `dmem` (64 KB) map to EBR block RAM

## LED Pinout (Ti60 F225 Dev Board, active-high)

| LED | Ball | Signal           |
|-----|------|------------------|
| 0   | K14  | Boot in progress |
| 1   | J15  | Running          |
| 2   | H10  | Fault            |

## UART Pinout

| Port    | Baud   | Content                                 |
|---------|--------|-----------------------------------------|
| ttyUSB2 | 57600  | Sapphire SoC greeting + CALLHOME JSON   |
| ttyUSB3 | 115200 | Church Machine NIA trace / fault events |
