bbenchoff/AGaMEMnon
GitHub: bbenchoff/AGaMEMnon
AGaMEMnon 是一款为 AGM AG32 RISC-V MCU（内置 AGRV2K FPGA 架构）打造的开源 SDK 与 FPGA 工具链，让用户摆脱厂商专有工具即可完成 Verilog 综合、布局布线、bitstream 生成和芯片烧录。
Stars: 23 | Forks: 1
# AGaMEMnon
[AG32](https://www.agm-micro.com/) 是一款内置了小型 FPGA 的微控制器。
它拥有一个真正的 RV32IMAFC 核心和硬核外设（UART、SPI、I²C、
CAN、USB、Ethernet MAC、定时器、ADC/DAC、GPIO），_此外_ 在这些外设
和引脚之间还有一小块可编程逻辑架构：
该架构既可以是独立的逻辑，也可以是硬核外设的引脚路由层，
或者是位于 MCU 旁边的内存映射协处理器。[AG32 概述](docs/AG32_OVERVIEW.md) 介绍了该器件、命名规则、时钟、
启动路径、封装以及文档概况。
这种可配置的逻辑架构就像胶水一样，几乎可以将任何引脚连接到任何外设。
你可以将 UART 路由到几乎任何引脚，在信号路径中加入状态机，在 CPU 旁边
添加一个小型定制外设，在运行时进行多路复用，并让所有这些都在启动时通过 SPI flash 进行配置。这使得 AG32 非常适合灵活的引脚
分配、协议粘合、确定性 IO 以及无需单独 FPGA 的
小型定制硬件。它有点像 Cypress PSoC，只不过可编程部分
是一个真正附加在 RISC-V 核心上的 FPGA。
```
flowchart LR
FW["RISC-V firmware"] --> MCU["RV32IMAFC MCU"]
MCU <--> AHB["AHB matrix"]
AHB <--> AHBP["AHB peripherals
USB OTG · CRC · RCU · flash · SRAM"] AHB <--> APB["AHB-to-APB bridge"] APB <--> HARD["Hard peripherals
UART · SPI · I²C · CAN · timers · RTC
watchdogs · ADC · DAC · comparator · GPIO"] RTL["Your Verilog"] --> FLOW["Yosys → nextpnr → AGaMEMnon bitgen"] FLOW --> FABRIC["AGRV2K FPGA fabric
LUTs · FFs · BRAM · routing"] AHB <--> PORTS["FPGA AHB
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 ``` AG32 几乎没有英文文档。“常规的”构建 bitstream 的方法是使用一个仅限 Windows 的 Altera Quartus II 分支版本（从百度网盘链接获取，提取码 `12ej`），并驱动一个黑盒架构后端 `af.exe`。它不支持 Linux，也没有开放的格式。如果你想 按照预期正常使用这颗芯片，简直难如登天。 *AGaMEMnon* 接收 Verilog 代码并生成可烧录的 AG32 架构 bitstream —— 包括综合、打包、布局布线、bitstream 生成和编程，全程 无需依赖任何厂商二进制文件。它是针对该芯片 RISC-V 部分的 SDK。这是一个为奇特的 RISC-V 微控制器与 FPGA 组合量身定制的 开源工具链。 它就是鲜为人知的芯片的 [IceStorm](https://github.com/YosysHQ/icestorm)。Verilog 经过综合、布局布线并在真实的硅片上运行： 包括组合逻辑和时序逻辑、计数器和状态机、阵列上的时钟、 输出到真实引脚，以及 RISC-V 核心通过其内存总线读写 逻辑架构。关于其工作原理的详细介绍在 [这里](http://bbenchoff.com/pages/AGaMEMnon.html)。 请观看视频演示： [][video-demo] ## 状态 AGaMEMnon 是一个**可通过源码安装的开发预览版**；目前还没有 可供下载的 SDK 发行版。当前的硬件目标是 **AG32VF303CCT6 LQFP-48 开发板**（配备 `AGRV2KL48` 架构）， 并且有意将支持范围限制得很窄且有据可查：对于不支持的封装、 布线和硬核块模式，工具链会直接报错中止，而不是 在不被支持的边界范围外悄悄生成镜像。确切的支持界限划分在 [支持矩阵](docs/STATUS.md) 和 [硬件验证记录](docs/HARDWARE_VALIDATION.md) 中；已知的差距 和优先推进的工作记录在 [ROADMAP.md](ROADMAP.md) 中。 ## 快速入门 ``` git clone https://github.com/bbenchoff/AGaMEMnon cd AGaMEMnon git lfs install git lfs pull python3 -m pip install -e ".[programming]" agamemnon doctor --no-hardware ``` 无需开发板或 FPGA 工具链即可进行尝试 —— 该代码库包含了一个已布线的 计数器测试套件： ``` agamemnon verify tests/fixtures/counter_ahb_routed.json --cycles 8 ``` 然后创建并运行你的第一个项目： ``` 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) ``` 要了解 AG32 与众不同之处，请使用 `--template mcu-fpga`：它的固件 会与一个定制的内存映射架构寄存器进行通信，并且在构建时会运行 Yosys 和 nextpnr。 环境设置分为多个层级，`agamemnon doctor` 会报告你当前处于哪个层级： 仅安装 Python 3.8+ 即可支持代码检查、转换和离线验证； 内置的 `riscv-none-elf-gcc`（或兼容的 `riscv64-unknown-elf-gcc`） 可额外支持 MCU 固件构建；Yosys 和 AGRV2K nextpnr 后端可额外支持架构构建；CMSIS-DAP 探针加上 AGaMEMnon 经过验证的 OpenOCD (`agamemnon install-openocd`) 则可支持芯片烧录。详见 [安装](docs/INSTALLATION.md)。 ## 硬件 对新手安全的传输方式是 SWD/DAP：它在全新原厂状态的板子上即可工作， 并且可以用于恢复变砖的板子。USB CDC 上传器在其加载程序安装完毕后， 将成为方便的常规应用传输方式，而基于 Pico 的 UART0 mask ROM 是 不依赖 flash 的恢复途径。在进行任何永久性写入之前，请先阅读[烧录](docs/PROGRAMMING.md)，并首先将你的开发板与 [已验证良好的硬件](docs/KNOWN_GOOD_HARDWARE.md) 进行比对。 ## 文档 | 阅读 | 了解内容 | |---|---| | [AG32 概述](docs/AG32_OVERVIEW.md) | 器件、命名、时钟、启动路径和厂商资源 | | [支持矩阵](docs/STATUS.md) | 明确列出受支持且经过芯片级验证的内容 | | [安装](docs/INSTALLATION.md) | Windows、Linux 和 macOS 上的工具链和驱动 | | [使用说明](docs/USAGE.md) | 完整的命令参考 | | [项目](docs/PROJECTS.md) | 清单、模板和项目模型 | | [烧录](docs/PROGRAMMING.md) | SWD/DAP、USB CDC 和 UART 传输方式及安全流程 | | [示例](examples/README.md) | 可运行的 RTL、固件、PCF 和 bitstream 配方 | | [MCU SDK](sdk/README.md) | 开源 HAL 及其验证状态 | | [MCU 时钟](docs/MCU_CLOCKS.md) | 核心架构时钟、过渡规则和电流限制 | | [MCU 引脚路由](docs/MCU_PIN_ROUTING.md) | 复用功能语义及基于芯片的支持布线策略 | | [架构](docs/ARCHITECTURE.md) | 逆向解析的架构和 bitstream 内部原理 | | [硬件验证](docs/HARDWARE_VALIDATION.md) | 芯片级的验证边界 | | [验证报告](docs/QUALIFICATION_REPORT.md) | 只读、可审查的支持证据汇总 | | [路线图](ROADMAP.md) | 已知限制和优先推进的工作 | | [声明](NOTICE.md) | 来源和许可边界 | ## 贡献与支持 新的硬件验证证据尤为珍贵。在提交代码或验证 记录之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)；当遇到与文档描述不符的问题时 请查阅 [SUPPORT.md](SUPPORT.md)；报告安全问题请遵循 [SECURITY.md](SECURITY.md)。用户可见的变更记录在 [CHANGELOG.md](CHANGELOG.md) 中。参与本项目受 [行为准则](CODE_OF_CONDUCT.md) 约束。 ## 名字的由来 AGaMEMnon。手头有“AG”可以发挥，加上“MEMory”（内存）的某种寓意。 我给它起这个名字的时候，诺兰的《奥德赛》还没上映。此外我也在为 [Marc Andreessen 在 Trump 彻底嗝屁时引用埃斯库罗斯（Aeschylus）的名言做心理准备](https://x.com/pmarca/status/1865145956230140134)。
| RISC-V MCU | FPGA 架构 |
|---|---|
|
|
USB OTG · CRC · RCU · flash · SRAM"] AHB <--> APB["AHB-to-APB bridge"] APB <--> HARD["Hard peripherals
UART · SPI · I²C · CAN · timers · RTC
watchdogs · ADC · DAC · comparator · GPIO"] RTL["Your Verilog"] --> FLOW["Yosys → nextpnr → AGaMEMnon bitgen"] FLOW --> FABRIC["AGRV2K FPGA fabric
LUTs · FFs · BRAM · routing"] AHB <--> PORTS["FPGA AHB
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 ``` AG32 几乎没有英文文档。“常规的”构建 bitstream 的方法是使用一个仅限 Windows 的 Altera Quartus II 分支版本（从百度网盘链接获取，提取码 `12ej`），并驱动一个黑盒架构后端 `af.exe`。它不支持 Linux，也没有开放的格式。如果你想 按照预期正常使用这颗芯片，简直难如登天。 *AGaMEMnon* 接收 Verilog 代码并生成可烧录的 AG32 架构 bitstream —— 包括综合、打包、布局布线、bitstream 生成和编程，全程 无需依赖任何厂商二进制文件。它是针对该芯片 RISC-V 部分的 SDK。这是一个为奇特的 RISC-V 微控制器与 FPGA 组合量身定制的 开源工具链。 它就是鲜为人知的芯片的 [IceStorm](https://github.com/YosysHQ/icestorm)。Verilog 经过综合、布局布线并在真实的硅片上运行： 包括组合逻辑和时序逻辑、计数器和状态机、阵列上的时钟、 输出到真实引脚，以及 RISC-V 核心通过其内存总线读写 逻辑架构。关于其工作原理的详细介绍在 [这里](http://bbenchoff.com/pages/AGaMEMnon.html)。 请观看视频演示： [][video-demo] ## 状态 AGaMEMnon 是一个**可通过源码安装的开发预览版**；目前还没有 可供下载的 SDK 发行版。当前的硬件目标是 **AG32VF303CCT6 LQFP-48 开发板**（配备 `AGRV2KL48` 架构）， 并且有意将支持范围限制得很窄且有据可查：对于不支持的封装、 布线和硬核块模式，工具链会直接报错中止，而不是 在不被支持的边界范围外悄悄生成镜像。确切的支持界限划分在 [支持矩阵](docs/STATUS.md) 和 [硬件验证记录](docs/HARDWARE_VALIDATION.md) 中；已知的差距 和优先推进的工作记录在 [ROADMAP.md](ROADMAP.md) 中。 ## 快速入门 ``` git clone https://github.com/bbenchoff/AGaMEMnon cd AGaMEMnon git lfs install git lfs pull python3 -m pip install -e ".[programming]" agamemnon doctor --no-hardware ``` 无需开发板或 FPGA 工具链即可进行尝试 —— 该代码库包含了一个已布线的 计数器测试套件： ``` agamemnon verify tests/fixtures/counter_ahb_routed.json --cycles 8 ``` 然后创建并运行你的第一个项目： ``` 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) ``` 要了解 AG32 与众不同之处，请使用 `--template mcu-fpga`：它的固件 会与一个定制的内存映射架构寄存器进行通信，并且在构建时会运行 Yosys 和 nextpnr。 环境设置分为多个层级，`agamemnon doctor` 会报告你当前处于哪个层级： 仅安装 Python 3.8+ 即可支持代码检查、转换和离线验证； 内置的 `riscv-none-elf-gcc`（或兼容的 `riscv64-unknown-elf-gcc`） 可额外支持 MCU 固件构建；Yosys 和 AGRV2K nextpnr 后端可额外支持架构构建；CMSIS-DAP 探针加上 AGaMEMnon 经过验证的 OpenOCD (`agamemnon install-openocd`) 则可支持芯片烧录。详见 [安装](docs/INSTALLATION.md)。 ## 硬件 对新手安全的传输方式是 SWD/DAP：它在全新原厂状态的板子上即可工作， 并且可以用于恢复变砖的板子。USB CDC 上传器在其加载程序安装完毕后， 将成为方便的常规应用传输方式，而基于 Pico 的 UART0 mask ROM 是 不依赖 flash 的恢复途径。在进行任何永久性写入之前，请先阅读[烧录](docs/PROGRAMMING.md)，并首先将你的开发板与 [已验证良好的硬件](docs/KNOWN_GOOD_HARDWARE.md) 进行比对。 ## 文档 | 阅读 | 了解内容 | |---|---| | [AG32 概述](docs/AG32_OVERVIEW.md) | 器件、命名、时钟、启动路径和厂商资源 | | [支持矩阵](docs/STATUS.md) | 明确列出受支持且经过芯片级验证的内容 | | [安装](docs/INSTALLATION.md) | Windows、Linux 和 macOS 上的工具链和驱动 | | [使用说明](docs/USAGE.md) | 完整的命令参考 | | [项目](docs/PROJECTS.md) | 清单、模板和项目模型 | | [烧录](docs/PROGRAMMING.md) | SWD/DAP、USB CDC 和 UART 传输方式及安全流程 | | [示例](examples/README.md) | 可运行的 RTL、固件、PCF 和 bitstream 配方 | | [MCU SDK](sdk/README.md) | 开源 HAL 及其验证状态 | | [MCU 时钟](docs/MCU_CLOCKS.md) | 核心架构时钟、过渡规则和电流限制 | | [MCU 引脚路由](docs/MCU_PIN_ROUTING.md) | 复用功能语义及基于芯片的支持布线策略 | | [架构](docs/ARCHITECTURE.md) | 逆向解析的架构和 bitstream 内部原理 | | [硬件验证](docs/HARDWARE_VALIDATION.md) | 芯片级的验证边界 | | [验证报告](docs/QUALIFICATION_REPORT.md) | 只读、可审查的支持证据汇总 | | [路线图](ROADMAP.md) | 已知限制和优先推进的工作 | | [声明](NOTICE.md) | 来源和许可边界 | ## 贡献与支持 新的硬件验证证据尤为珍贵。在提交代码或验证 记录之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)；当遇到与文档描述不符的问题时 请查阅 [SUPPORT.md](SUPPORT.md)；报告安全问题请遵循 [SECURITY.md](SECURITY.md)。用户可见的变更记录在 [CHANGELOG.md](CHANGELOG.md) 中。参与本项目受 [行为准则](CODE_OF_CONDUCT.md) 约束。 ## 名字的由来 AGaMEMnon。手头有“AG”可以发挥，加上“MEMory”（内存）的某种寓意。 我给它起这个名字的时候，诺兰的《奥德赛》还没上映。此外我也在为 [Marc Andreessen 在 Trump 彻底嗝屁时引用埃斯库罗斯（Aeschylus）的名言做心理准备](https://x.com/pmarca/status/1865145956230140134)。
标签：FPGA, RISC-V, SoC, 嵌入式系统, 开发工具链, 微控制器, 硬件驱动, 逆向工具