# FT-710_Firmware

An analysis of the Yaesu FT-710 firmware. The goals are to understand the radio, find undocumented CAT commands, and eventually build custom firmware.

## Progress

<!-- progress:begin -->
**Understood: 91.4 % of the code** (bytes in named functions), **89.3 % documented**, **100.0 % decompiled**, across the three CPU images. The SDR FPGA's netlist is fully recovered, **37.2 % recognized** and **9.3 % re-implemented** in RTL (in netlist cells, second table; see [docs/code/sdr](docs/code/sdr/README.md)).

| Image | Functions | Code | Decompiled | Named | Documented | Calls named | Registers named | Variables named | Commented | Re-implemented |
|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
| MAIN (RX651) | 2,812 / 3,794 | 378 KB | 100.0 % | 87.0 % | 86.3 % | 84.7 % | 99.8 % | 13.8 % | 27.8 % | 24.8 % |
| DISPLAY (RZ/A1H) | 1,955 / 2,245 | 387 KB | 100.0 % | 93.7 % | 89.7 % | 94.0 % | 99.5 % | 6.8 % | 31.4 % | 22.0 % |
| IFDSP M33 (RT685) | 450 / 450 | 29 KB | 100.0 % | 100.0 % | 100.0 % | 100.0 % | 100.0 % | 9.6 % | 30.2 % | 100.0 % |
| IFDSP HiFi4 (RT685) | 954 / 1,081 | 176 KB | 100.0 % | 94.3 % | 92.9 % | 90.0 % | 99.6 % | 0.4 % | 17.9 % | 3.2 % |
| **All CPU images** | 6,171 / 7,570 | 970 KB | 100.0 % | 91.4 % | 89.3 % | 89.8 % | 99.7 % | 6.9 % | 27.6 % | 22.0 % |

*Functions* = named / total. Percentages are of code bytes, except *Calls named* (call sites), *Registers named* (peripheral-register references) and *Variables named* (uses of parameters and local variables in the function bodies whose name is not a Ghidra default such as `param_1`, `uVar3`, `local_1c`, `auStack_20`, `in_r0`, `unaff_r4` or `extraout_r1`). *Decompiled* = in functions Ghidra decompiles without a failure; *Named* = in functions with a real name instead of `FUN_<address>`; *Documented* = in named functions that the `docs/code/` pages mention; *Commented* = functions (share of all) whose decompiled C has at least one short inline comment with its evidence tag (a register name, a callee's documented purpose, an enum value or a curated step note; [T23i](docs/tasks/T23-readability.md#t23i--inline-comments)); *Re-implemented* = in functions whose recreated source in `src/<image>/` compiles to the same bytes or passes the differential-emulation equivalence check (`src/<image>/status.tsv`, [T24](docs/tasks/T24-source-recreation.md)). Generated by `tools/readability_stats.py` from the committed `decomp/` export; the plan to raise these numbers is [T23](docs/tasks/T23-readability.md).

| FPGA image | Netlist cells | Recovered | Recognized | Re-implemented |
|---|---:|---:|---:|---:|
| SDR (XC7A50T) | 63,735 | 100.0 % | 37.2 % | 9.3 % |

*Netlist cells* = LUTs, flip-flops, carry chains, DSP and block-RAM sites, clock buffers and pins of the netlist recovered from the bitstream (an FPGA has no functions to count). *Recovered* = in the netlist; *Recognized* = attributed to one of the 43 blocks documented in [netlist.md](docs/code/sdr/netlist.md) (seed cells grown by fan-in/fan-out cones); *Re-implemented* = in blocks whose hand-written RTL in [hdl/sdr](hdl/sdr/README.md) is verified against the netlist (`adc_combine.v`, `adc_dc.v`, `adc_gain.v`, `regfile.v`, `regread.v`, `rx_fir_operand_mux.v`, `rx_out_mac.v`, `rx_window_sum.v`, `scope_spi.v`, `scope_wr_addr.v`, `scope_wr_data.v`, `scope_wr_seq.v`, `uart_console.v`, `uart_link.v`, `uart_rx.v`). Generated by `tools/sdr_progress.py` into `decomp/sdr/progress.tsv`.
<!-- progress:end -->

**Custom firmware** (projects that change the radio: designs, patches, tests) lives in
**[Reid-n0rc/FT-710_Custom_Firmware](https://github.com/Reid-n0rc/FT-710_Custom_Firmware)**, which builds on this repository
(pinned as a submodule) and follows it automatically. This repository stays the place for facts about the stock firmware.

**Agents and contributors: start with [AGENTS.md](AGENTS.md).** The task board is in [docs/tasks/README.md](docs/tasks/README.md).

## New here? Read the illustrated guide

**[docs/guide/README.md](docs/guide/README.md)** explains the whole radio in plain language, in one document with a table of contents,
74 pictures and diagrams, and a glossary. The project's website, **https://reid-n0rc.github.io/FT-710_Firmware/**, has the highlights and the undocumented CAT command
documentation. The guide is also published as the [wiki](https://github.com/Reid-n0rc/FT-710_Firmware/wiki), one page per
chapter. Start there; the reference pages below hold the detail and the evidence.

## How the radio is built

The FT-710 runs four firmware images on four devices. The DISPLAY CPU owns the front panel and the SD card, wakes the MAIN CPU and updates
every other image. The MAIN CPU owns the radio state and CAT, and drives the SDR FPGA and the IF DSP over register-style UART links. Start with
**[docs/code/system.md](docs/code/system.md)**: block diagrams, the inter-CPU protocols, and the power-on, update, CAT, tuning, transmit and
scope flows across all four images.

| Image (SFL tag) | Device | Role | Code documentation |
|---|---|---|---|
| MAIN (`MC`) | Renesas RX651, MAIN unit | control CPU: radio state, CAT, EEPROM, TX/RX sequencing, links to the other CPUs | [docs/code/main/README.md](docs/code/main/README.md) |
| DISPLAY (`PC`) | Renesas RZ/A1H, DISPLAY unit | touch GUI, keys and encoders, SD card, firmware updates, USB scope stream | [docs/code/display/README.md](docs/code/display/README.md) |
| IFDSP (`ID`) | NXP i.MX RT685 (Cortex-M33 + HiFi4), MAIN unit | IF/AF signal processing, codec | [docs/code/ifdsp/README.md](docs/code/ifdsp/README.md) |
| SDR (`SR`) | Xilinx Artix-7 XC7A50T, SDR module | ADC, down-/up-conversion, scope data (bitstream, no CPU) | [docs/code/sdr/README.md](docs/code/sdr/README.md) |

Other references: [hardware survey](docs/hardware.md), [memory maps](docs/memory-maps.md), [CAT commands](docs/cat-commands.md),
[SFL file format](docs/sfl-format.md), [custom-firmware feasibility](docs/custom-firmware.md), [tooling](docs/tooling.md).
Decompiled code is in `decomp/<image>/`.

## Getting started: rebuild everything from the official downloads

**[docs/getting-started.md](docs/getting-started.md)** is the manual for newcomers: prerequisites per OS, getting the inputs, the
bootstrap, a tour of the repo, Ghidra (and optionally REA), the conventions and how to contribute. In short:

```sh
mkdir -p Firmware && curl -fL -o Firmware/FT-710_Firmware_updata_202402.zip \
  https://yaesu.com/Files/BB2B47AE-1018-01AF-FAE48FDCB1919193/FT-710_Firmware_updata_202402.zip
tools/bootstrap.sh            # decode, build the Ghidra projects with every name, re-export, diff against decomp/
```

The manuals (`Manuals/`) and the three canonical Ghidra projects (`ghidra/`) are in the repo. Only Yaesu's firmware download (`Firmware/`)
and the decoded images (`build/`) are fetched and rebuilt locally; `tools/bootstrap.sh` reproduces them byte for byte (hashes in
[docs/inputs.sha256](docs/inputs.sha256)) and can also rebuild the Ghidra projects from scratch. Full instructions:
[docs/getting-started.md](docs/getting-started.md). The manuals and datasheets, with their sources, are listed in
[docs/manuals.md](docs/manuals.md); the scripts in [tools/README.md](tools/README.md). Open questions are GitHub issues (see
[CONTRIBUTING.md](CONTRIBUTING.md)).