isa-instruction-lookup

ISA Instruction Lookup

查询官方 ISA 规格的统一入口。数据只来自权威来源，经离线 ingest 进入 mcp/isa-reference/data/isa.db，通过 MCP 工具只读查询。

当前库覆盖：

• a64（2259 条，ARM-official XML 2026-06）：编码/伪代码/FEAT_xxx 全量
• x86_64（854 条 = Intel-SDM 771 + AMD-APM 特有 83）：opcode 表/伪代码/ CPUID:XXX feature（Intel opcode 表 feature 列 + AMD 页内声明双源，约 1700 行）

何时用

• 读 JIT/反汇编机器码，要确认某助记符的编码、操作数约束或执行语义
• codegen 优化：找"做某件事"的指令（如条件选择、位反转、批量内存操作）
• 判断某指令依赖哪个 FEAT_xxx，目标环境（Kunpeng 等）是否实现
• 跨平台比对：某 A64 指令在 x86 侧的等价候选（或反向）

三层检索流程

按顺序降级，不要跳层：

1. 意图映射：查询是优化意图（如"用条件选择取代比较和分支"）时，先读 references/optimization-intent-map.md 把意图翻译成功能术语（→ "conditional select"）。 已知助记符（如反汇编输出里的 CSEL）跳过此层。
2. 功能检索：find_instruction_by_function(description="conditional select") — FTS 匹配 brief/authored，返回候选列表。描述用英文功能术语。 候选检索跨 category/feature 不设限——优化替换经常跨执行域（base 需求 用 SIMD 指令满足、SVE 替换 base 序列），分类和 feature 只是可用性维度， 不是过滤条件。
3. 精确查询与查证：候选定位后 lookup_instruction(mnemonic, verbose=True)。 查证主体与必做动作：
   • operation_pseudocode——方案的每条语义假设（"无条件写 Rd"）逐行比对， 不一致即方案错误；
   • asm_templates——合法语法形态，写汇编/lowering 的依据；
   • operand_docs——操作数约束（宽度限制、内存源语义、编码位要求）， 编码陷阱在这里暴露；
   • bitfields——具体编码位。 category 只用于同名消歧，features 只用于环境部署判定——这两者不是 语义查证的输出，只回答"是 base 类/无 feature 依赖"不构成查证。

跨平台等价：find_equivalent_instruction(mnemonic, from_arch, to_arch)。返回的是 词面候选（如 CMOVcc 的 a64 侧候选会混入 MOV 族）——先查 references/optimization-intent-map.md 的跨平台族映射（权威答案），机器候选用于 发现遗漏，精确等价性必须比对双方 operation_pseudocode 后下结论。

环境可用性判定

1. 环境侧 feature 列表：a64 来自 /proc/cpuinfo 或 ID_AA64* 系统寄存器解读 （环境审计走 cinderx-env-validate）；x86_64 来自 CPUID flag 名（如 BMI2、SSE2），传入时带 CPUID: 前缀或由工具直接匹配 flag 名。
2. filter_by_environment(env_features=[...], arch=...) 返回 available / conditional / unavailable。conditional 表示该指令可用性还依赖 操作数取值（如 sz 字段），必须读该指令 bitfields 后人工判读。
3. 同名指令跨执行域变体（ABS 有 base/SIMD/SVE 三版）靠返回的 category 消歧。

硬规则

• 库内 source_authority 只允许官方来源白名单，规则见 references/source-authority-policy.md。非官方来源数据一律不入库。
• 指令的微架构性能（吞吐/延迟）不在本库——ISA 手册不含性能数据， 性能结论走 perf/TRM 路径（cinderx-isa-microarch-compare）。
• 引用指令规格时必须带上来源（source_doc + page_start），便于回溯。
• 数据更新（新版本手册/新架构）只跑 mcp/isa-reference/scripts/ingest_*.py 重建，不手改 isa.db。