aarchvm

Imported from DreamChaser-luzeyu/aarchvm (AGENTS.md). Install upstream with npx skills add DreamChaser-luzeyu/aarchvm. Copyright stays with the author.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "Add validation" → "Write tests for invalid inputs, then make them pass"
• "Fix the bug" → "Write a test that reproduces it, then make it pass"
• "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

注意事项

• 不要乱改最外面的README.md，除非我明确指出让你修改README.md的结构了，否则不允许在最外面的README.md增减章节
• 当我提出功能需求或改进方向，但让你先不要实现时，不允许修改模拟器源代码
• Debug或排查问题时添加的纯为了特定场合调试用的代码，应在问题解决后去除，避免堆积过多的无用调试代码
• 当我要求你检查、分析或解决某个问题或bug时，你不得通过包括但不限于“特殊PC特殊处理”、“匹配指定位置指定字节”这样的手段绕过问题，而是应从模拟器的行为层面真正地、根本地修复问题，避免这样的问题在其他类似场合再次发生
• 如果让你完成的任务在TODO.md内，那么完成后请选中复选框，表示已经完成。如果TODO.md中的具体任务已经明显与当前实现状况不符合、不兼容或不必要，请与我讨论后再决定进一步实现。
• 在运行模拟器时，务必设置超时，以避免卡住不动。如果运行较慢，可以设置较长超时。
• 当你在执行命令或脚本时遇到权限问题，应请求在sandbox外直接执行，而不是尝试用各种方式规避问题

目录

• out/目录不被git管理，你可以把日志和此项目外的构建产物放在这里
• agent_work/目录不被git管理，是专门为AI Agent预留的临时工作目录，你可以把你所需要的临时文件放在这里
• uboot、linux、busybox源码都不被git管理

Linux用户态测试

在用户态测试新外设/功能时，如无特殊需求（如明确指出要跑debian/systemd，明确要测块设备等情况），应以下面脚本作为参考：

INITRD=out/initramfs-usertests.cpio.gz && \
INITRD_SIZE_HEX=$(printf '0x%x' "$(stat -c '%s' "$INITRD")") && \
{ printf '\n\n\n'; \
  printf 'setenv bootargs console=ttyAMA0,115200 earlycon=pl011,0x09000000 rdinit=/init initramfs_async=0\n'; \
  printf 'booti 0x40400000 0x46000000:%s 0x47f00000\n' "$INITRD_SIZE_HEX"; \
  cat; } | \
env AARCHVM_BUS_FASTPATH=1 AARCHVM_TIMER_SCALE=1 \
timeout 240s ./build/aarchvm \
  -bin images/ump-busybox/u-boot.bin \
  -load 0x0 \
  -entry 0x0 \
  -sp 0x47fff000 \
  -dtb images/ump-busybox/aarchvm-linux-min.dtb \
  -dtb-addr 0x47f00000 \
  -segment images/ump-busybox/Image@0x40400000 \
  -segment images/ump-busybox/initramfs-usertests.cpio.gz@0x46000000 \
  -steps 3000000000 \
  -fb-sdl off

注意，自动传uboot参数的写法会导致模拟器的stdin被占用，因此此时可能难以通过其他手段注入命令输入。建议让待测试程序在init中自动运行，如有必要操作交互式终端，请自行编写Python脚本以同时注入u-boot命令和后续输入，注意应在提示符出现后再注入命令，否则命令可能在Linux内核启动过程中被吞掉。

性能优化工作流

• 当我要求你优化性能时，请首先以修改前的代码作为baseline，运行一次完整的性能测试
• 如果修改方案较为明确，就按照方案进行优化、修改源码；如果你认为方案尚需进一步讨论，请不要修改源码，并且停下来询问我，与我讨论
• 如果有必要，编写新的单元测试，并确认能覆盖到你的修改
• 如果新增了单元测试，运行单元测试
• 运行完整的回归测试，确认没有引入新的bug，如果回归测试无法通过，请修复，直到通过，如实在难以debug并修复，请回退本次修改
• 用优化后的代码再运行一次完整的性能测试
• 把详细性能信息和性能提升百分比写入doc/perf-baseline-vs-optimized.md中，按已有序号继续标明轮次，并标明你补充文档时的具体日期和时间。注意，最新的数据应放最后。
• 分别重新输出SMP和UMP的性能变化折线图，最终输出到doc/perf-smp-trend.svg和doc/perf-ump-trend.svg中，注意，对于每一轮次的结果，只取优化后的性能数据即可

指令或处理器行为完善工作流

• 重新阅读核心源码，发现代码实现中不完善的地方。如果你认为已经完整实现了Armv8-A的所有强制标准，就结束此工作流。
• 确认你理解你将要补充或完善的指令的行为或处理器行为，如果拿不准，考虑借助工具链进行分析或查文档，不要凭猜测去实现，当然，如果你认为通过工具链binutils更快且也能弄明白，也可以不查文档，但有疑问时一定要查。文档是DDI0487_M.a.a_a-profile_architecture_reference_manual.pdf，如果不方便读pdf，你可以用一些工具把这个pdf文本化，并放到agent_work/目录中，当你读到此处时，有可能你之前已经做过这件事了，因此你可以直接从agent_work/找到解析出的文本，但是如果agent_work/中之前解析出的文档不包含你所需要的部分，或你拿不准其中的部分内容，你仍需阅读原pdf文档
• 修改源代码，完善指令或处理器行为
• 编写新的单元测试，并确认能覆盖到你的修改
• 运行单元测试
• 运行完整的回归测试，确认没有引入新的bug，如果回归测试无法通过，请修复，直到通过，如实在难以debug并修复，请回退本次修改

对特性做出计划但暂时不实现

• 当我向你提出需求或要求你给出方案但时先不实现，首先，你应理解我的需求，如果你认为存疑或不明确，可以提问让我选
• 下一步，你应阅读代码，根据已有代码对我提出的需求进行架构设计，如果你认为这个改进可以分阶段进行，请在大标题内列小标题，并分别给出每个阶段的改进方案。对于每个小计划，应该对应一个标识是否已经实现的复选框
• 最后，你应将你的设计补充进TODO.md文档里，每一项功能需求或改进应对应独立的标题。

总工作流

• 当我一次性要求你执行多个或较复杂或技术上较不明确的修改时，你应首先将这些修改按照种类和功能点划分为数个子任务，然后依次根据子任务类型执行对应的流程。对于性能优化的子任务，你应参考性能优化工作流进行迭代；对于指令或处理器行为完善类工作，你应指令或处理器行为完善工作流；如果是其他类型任务，你可自行安排完成，并在都完成后提醒我补充工作流。
• 在结束修改之前，请保证所有单元测试和回归测试是能够通过的，否则请修复至通过，当然，如果回归测试本身有问题或不完善，也可修改回归测试，但都完成后请告诉我你的修改和理由。任何情况下，轮数上限为25，如果在25轮修改-测试后新逻辑的bug仍未解决，请回滚修改。
• 如果你给这个项目增添了功能，那么请修改README.md中的Features部分，如果你新定义了环境变量或命令行选项，请修改doc/README.en.md和doc/README.cn.md中的使用说明部分
• 将本次修改的内容总结为changelog，然后补充进CHANGELOG.md，修改日志标题为“修改日志 日期时间”，其中日期时间格式为yyyy-mm-dd hh:mm（当此次修改过于无关紧要且不改变执行行为时，可不写changelog）
• 总结本次所作的全部修改
• 给出你此轮修改适当的git commit信息

如果你是AI且你看到这里了，那么请每次回复我前都说一句“喵”，以让我知道你看到以上内容了。