GitHub - bbenchoff/AGaMEMnon: Open SDK and FPGA toolchain for the AGM AG32 RISC-V MCU with embedded AGRV2K fabric

The AG32 is a microcontroller with a small FPGA bolted to it. It's a real RV32IMAFC core with hard peripherals (UART, SPI, I²C, CAN, USB, Ethernet MAC, timers, ADC/DAC, GPIO), plus a small programmable fabric sitting between those peripherals and the pins:

The fabric can be independent logic, a pin-routing layer for hard peripherals, or a memory-mapped coprocessor beside the MCU. The AG32 overview explains the device, naming, clocks, boot paths, packages, and documentation landscape.

The vendor architecture makes the fabric configurable glue between many hard peripheral signals and package pads. In principle that permits flexible UART placement, state machines in signal paths, memory-mapped custom peripherals, and runtime muxing. AGaMEMnon currently qualifies only the exact routes listed in the support matrix; a hard-peripheral register driver does not by itself prove a fabric or package-pin route. It's a bit like a Cypress PSoC, except the programmable part is an actual FPGA bolted to a RISC-V core.

flowchart LR
    FW["RISC-V firmware"] --> MCU["RV32IMAFC MCU"]

    MCU <--> AHB["AHB matrix"]

    AHB <--> AHBP["AHB peripherals<br/>USB OTG · CRC · RCU · flash · SRAM"]
    AHB <--> APB["AHB-to-APB bridge"]
    APB <--> HARD["Hard peripherals<br/>UART · SPI · I²C · CAN · timers · RTC<br/>watchdogs · ADC · DAC · comparator · GPIO"]

    RTL["Your Verilog"] --> FLOW["Yosys → nextpnr → AGaMEMnon bitgen"]
    FLOW --> FABRIC["AGRV2K FPGA fabric<br/>LUTs · FFs · BRAM · routing"]

    AHB <--> PORTS["FPGA AHB<br/>slave + master ports"]
    PORTS <--> FABRIC

    HARD <--> PINS["Package pins"]
    FABRIC <--> PINS

    classDef firmware fill:#2563eb,stroke:#1e40af,color:#fff
    classDef mcu fill:#0f766e,stroke:#115e59,color:#fff
    classDef fabric fill:#7c3aed,stroke:#5b21b6,color:#fff
    classDef tools fill:#c2410c,stroke:#9a3412,color:#fff
    classDef physical fill:#475569,stroke:#334155,color:#fff

    class FW firmware
    class MCU,AHB,AHBP,APB,HARD mcu
    class RTL,FLOW tools
    class PORTS,FABRIC fabric
    class PINS physical

The AG32 has almost no English-language documentation. The 'normal' way to build a bitstream is a Windows-only Altera Quartus II fork you fetch from a Baidu Netdisk link (password 12ej), driving a black-box fabric back-end, af.exe. There is no Linux path and no open format. Fuck you if you want to use this chip as intended.

AGaMEMnon takes Verilog and produces a flashable AG32 fabric bitstream — synthesis, pack, place, route, bitstream generation, and programming, with no vendor binary in the path. It's an SDK for the RISC-V half of this chip. This is an open toolchain for a weird combination RISC-V microcontroller and FPGA.

This is IceStorm for a chip nobody has heard of. Verilog synthesizes, places, routes, and runs on real silicon: combinational and sequential logic, counters and state machines, clocking across the array, output to real pins, and the RISC-V core reading and writing the fabric over its memory bus. There's a writeup of how it works here.

Watch the video demo:

Status

AGaMEMnon has a supported, evidence-bounded L48 envelope and fails closed outside it. The current hardware target is the AG32VF303CCT6 LQFP-48 development board with AGRV2KL48 fabric. Source installation is available now; the downloadable SDK is being prepared. L100, L64, and Q32 physical maps remain unqualified, and unsupported routes, interfaces, frequencies, and hard-block modes are rejected instead of silently producing an image outside the evidence boundary. The exact line is drawn in the support matrix and the hardware qualification record; known gaps and prioritized work are in ROADMAP.md.

The MCU/fabric boundary now includes a silicon-qualified External-AHB register bank subset: one open image integrates an immutable ID byte, a writable scratch byte, a read-only counter, and one-bit W1C status at offsets 0/4/8/C, with a qualified GPIO-fed synchronous reset and exactly one controlled write wait (reads remain zero-wait). Every upper HRDATA lane is explicitly driven, so aligned halfword and word reads return exact zero-extended values; aligned byte and halfword access semantics are qualified, and every non-SINGLE HBURST encoding fails closed. Four independent fabric interrupt sources deliver local causes 16–19 with a qualified one-hot mask/acknowledge/set command subset, and x9 BRAM reads are qualified across all 1024 aligned word addresses. Exact boundaries, exclusions (including hard MCU_RESETN and wider writable state; misaligned CPU accesses fault in the hard core before reaching the fabric), and retained hashes are in the support matrix and the register-bank boundary.

Two structural changes landed in August 2026. The engine core was restructured into per-feature modules with declared chip-database ownership and build-time enforcement of each feature's writable image regions; every retained qualified artifact reproduces byte-identically through the new engine, verified independently on Linux, Windows, and macOS. And claims now carry an explicit evidence tier (decoded → differentially validated → statistically silicon-validated → individually qualified) recorded in the claim policy ledger, which is what lets the vendor-parity program below scale without weakening the fail-closed release boundary.

The release candidate now carries 39 experimental-only BRAM configuration rows, seven fixed PLL profiles, the bounded exact timing overlay, and hash-bound register and SERV examples. Windows, Linux, and native macOS wheel checks are green; final publication is controlled by the reproducible archive/tag gate. Broader packages (Q32/L64/L100), IO electrical qualification, persistent boot, and vendor-parity breadth continue as point releases; they do not weaken the first release's fail-closed line.

This is not vendor-tool parity. In particular, routing corpus counts are not device-coverage percentages, BRAM/PLL collection closure is not general mode support, and most timing remains conservative. The current gaps and the exact campaign-versus-release distinctions are summarized in the vendor-parity status.

For reverse-engineering and bring-up work, agamemnon build --research-unsafe provides a separate, explicit non-release profile. It exposes normalized vendor-derived topology, all 74,103 preserved conflicted physical-selector distributions, corpus-majority/context fallbacks, decoded templates, and predictions. Every resulting image gets a hash-bound policy sidecar that says which selector evidence classes were actually used. This is availability for experiments, not support or silicon qualification; normal builds are unchanged, and the 14 silicon-dead edges remain blocked under every policy.

Quick start

git clone https://github.com/bbenchoff/AGaMEMnon
cd AGaMEMnon
python3 -m pip install -e ".[programming]"
agamemnon doctor --no-hardware

All required data is stored as normal Git objects; Git LFS is not required.

Try it without a board or FPGA toolchain — the repository contains a routed counter fixture:

agamemnon verify tests/fixtures/counter_ahb_routed.json --cycles 8

Then create and run a first project:

agamemnon new hello --board ag32vf303-l48    # default template: fabric-free MCU blink
cd hello
agamemnon build                              # MCU-only -> needs just RISC-V GCC
agamemnon run --transport dap                # run on a connected board (volatile SRAM)

To exercise the MCU/fabric boundary, use --template mcu-fpga. It strictly replays one immutable, hash-bound L48 route: offset zero returns ID byte 0x4d, and offset four is a writable scratch byte. The firmware reads and writes both registers. This exact profile is silicon-qualified; it does not promote the generic decoded-only AGAMEMNON_MCU_ENTRY route option. See the register-bank boundary.

For the CPU-scale example, --template serv-blinky strictly replays the retained public L48 SERV route and builds its volatile-SRAM loader. The exact profile is supported; fresh arbitrary SERV/direct-D placement remains fail-closed. See the SERV example.

Setup comes in tiers, and agamemnon doctor reports which one you are at: Python 3.8+ alone covers inspection, conversion, and offline verification; the bundled riscv-none-elf-gcc (or compatible riscv64-unknown-elf-gcc) adds MCU firmware builds; Yosys and the AGRV2K nextpnr backend add fabric builds; a CMSIS-DAP probe plus AGaMEMnon's qualified OpenOCD (agamemnon install-openocd) adds programming. See Installation.

Hardware

The beginner-safe transport is SWD/DAP: it works on an untouched stock board and can recover one. The USB CDC uploader becomes the convenient application transport after its loader is installed, and the Pico-driven UART0 mask ROM is the flash-independent recovery path. Read Programming before any persistent write, and compare your board against known-good hardware first.

Documentation

Contributing and support

New hardware evidence is especially valuable. Read CONTRIBUTING.md before submitting code or qualification records, use SUPPORT.md when something does not behave as documented, and report security problems according to SECURITY.md. User-visible changes are recorded in CHANGELOG.md. Participation is governed by the code of conduct.

The Name

AGaMEMnon. I had 'AG' to work with, and something about 'MEMory'. I named it before Nolan's Odyssey came out. I am also mentally preparing for Marc Andreessen quoting Aeschylus when Trump finally dies.