AME Matmul and RVV Softmax

本仓库包含两个可独立复现的 RISC-V C 算子：

目录	算子	运行方式	结果
matmul_ame/	AME int8 matmul	交叉编译为 FPGA bin	build/models_ame_matmul_fpga.bin
softmax_rvv/	RVV FP32 softmax	QEMU RV64 用户态	512 项与标量参考比较并打印 PASS

项目源码和辅助文件全部在本仓库内。外部只需要编译器、RISC-V sysroot/binutils 和 QEMU，不需要 Qwen 模型权重。

1. 推荐环境

• x86_64 Ubuntu 24.04（22.04 也可）
• 至少 15 GB 可用磁盘（主要用于构建定制 LLVM）
• 建议 8 GB 以上内存
• 网络可访问 GitHub 和 Ubuntu 软件源

本仓库已验证的工具版本：

RuyiAI clang 23.0.0git, commit 926a1ea856cbb7978514c7c960aa16c3a835381c
riscv64-linux-gnu-gcc 13.3.0
GNU binutils 2.42
qemu-riscv64 11.0.0

2. 安装基础依赖

sudo apt update
sudo apt install -y \
  git make cmake ninja-build build-essential \
  gcc-riscv64-linux-gnu binutils-riscv64-linux-gnu \
  qemu-user

确认发行版工具可用：

riscv64-linux-gnu-gcc --version
riscv64-linux-gnu-objcopy --version
riscv64-linux-gnu-readelf --version
qemu-riscv64 --version
test -d /usr/riscv64-linux-gnu && echo "RISC-V sysroot OK"

3. 获取仓库

git clone https://gitlink.org.cn/michaelcjl/kernel_c.git
cd kernel_c

4. 构建定制 LLVM（matmul 必需）

AME matmul 使用 msettile*、mlce32、msce32、mqma.b.mm 等扩展指令。 Ubuntu 自带的 clang 不支持这些指令，不能用于构建 matmul。

使用已验证的 RuyiAI LLVM fork：

mkdir -p "$HOME/opt"
git clone https://github.com/RuyiAI-Stack/llvm-project.git \
  "$HOME/opt/llvm-project-riscv"
cd "$HOME/opt/llvm-project-riscv"
git checkout 926a1ea856cbb7978514c7c960aa16c3a835381c

cmake -S llvm -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_ENABLE_PROJECTS="clang" \
  -DLLVM_TARGETS_TO_BUILD="RISCV"

ninja -C build clang

记录 clang 路径：

export AME_CLANG="$HOME/opt/llvm-project-riscv/build/bin/clang"
"$AME_CLANG" --version

若已经拿到同一 fork 的预编译 clang，可跳过源码构建，直接让 AME_CLANG 指向该可执行文件。

5. 生成 AME matmul FPGA bin

cd /path/to/kernel_c/matmul_ame
make clean
make CLANG="$AME_CLANG"
make verify CLANG="$AME_CLANG"

成功时会看到：

Generated: build/models_ame_matmul_fpga.bin
Entry point address: 0x86400000

主要产物：

matmul_ame/build/models_ame_matmul_fpga.bin
matmul_ame/build/models_ame_matmul_fpga.elf
matmul_ame/build/models_ame_matmul_fpga.map

bin 的加载/入口地址为 0x86400000，UART MMIO 地址为 0x10000000。 该 bin 用于 FPGA，不在普通 QEMU 中执行。

如果提示 AME 指令需要 XBOSCAME，说明使用了错误的 clang，或使用的 RuyiAI LLVM 版本与上述 commit 不一致。

6. 在 QEMU 运行 RVV softmax

softmax 不需要定制 LLVM，使用发行版 RISC-V GCC 即可：

cd /path/to/kernel_c/softmax_rvv
make clean
make run
make verify

make run 实际执行：

qemu-riscv64 -cpu rv64,v=true,vlen=256,elen=64 build/rvv_softmax

程序会打印 512 行逐元素比较：

index | input | RVV output | reference | abs diff | status

结尾应为：

elements=512 passed=512 failed=0
PASS

主要产物：

softmax_rvv/build/rvv_softmax
softmax_rvv/build/rvv_softmax_qemu.log

可测试其他向量长度：

make clean
make QEMU_CPU='rv64,v=true,vlen=128,elen=64' run
make QEMU_CPU='rv64,v=true,vlen=512,elen=64' run

7. 常见问题

clang-23: command not found

matmul Makefile 默认查找 clang-23。推荐始终显式指定：

make CLANG="$HOME/opt/llvm-project-riscv/build/bin/clang"

instruction requires ... XBOSCAME

当前 clang 不包含或没有正确启用 RuyiAI AME 扩展。使用第 4 节指定的 fork 和 commit，不要使用 Ubuntu 官方 clang。

riscv64-linux-gnu-objcopy: command not found

sudo apt install binutils-riscv64-linux-gnu

cannot find -lgcc 或找不到 RISC-V 头文件

sudo apt install gcc-riscv64-linux-gnu
test -d /usr/riscv64-linux-gnu

QEMU 提示 CPU 属性或 RVV 指令不支持

确认使用的是 qemu-riscv64（用户态模拟器），并升级到支持 RVV 1.0 的 较新 QEMU。运行以下命令检查：

qemu-riscv64 -cpu rv64,v=true,vlen=256,elen=64 \
  softmax_rvv/build/rvv_softmax

8. 独立性说明

• matmul_ame/Makefile 的所有源码、头文件、启动文件和链接脚本均来自 matmul_ame/ 内部。
• softmax_rvv/Makefile 只读取本目录的 rvv_softmax.c 和 rvv_common.h。
• 两个目录都不读取其他项目的源码或对象文件。
• 编译器、sysroot、libgcc、静态 libc、binutils 和 QEMU 属于外部工具链。