# isa

**归执行器侧**，只管指令定义。CMake 目标：`isa`（`STATIC`），无依赖；被 `vm` 依赖。

`compiler` **不依赖 isa**——指令 opcode / 类型元数据 / FB 布局全部来自 `compiler/machine.toml`（见 [`指令配置.md`](../doc/isa/指令配置.md)）。`.stb` 映像读写由 `compiler`（写侧）与 `vm`（读侧）**各自实现**。

```text
STCompiler      → compiler        （编码查 machine.toml，自带 .stb 写）
BytecodeExecutor → vm → isa        （isa 只管指令；vm 自带 .stb 读）
```

**操作码、指令字以** [`doc/isa/指令与映像.md`](../doc/isa/指令与映像.md) **为准。** 头文件实现该文，本 README 不另当规范。`.stb` 结构拆解见 [`doc/isa/stb文件格式.md`](../doc/isa/stb文件格式.md)。指令/类型/FB 登记见 [`doc/isa/指令配置.md`](../doc/isa/指令配置.md)。

公开头：`isa/include/isa/`。

---

## 做 / 不做

**做：** 操作码与 32-bit 指令字、`BOOL`/`INT`/`TIME` 定宽与饱和、编解码、一条指令的文本转储。

**不做：** 映像读写（compiler/vm 各自实现）、toml/关键字/符号表/AST、VM 执行 switch（在 `vm`）、扫描周期、I/O 采样。

---

## 目录与 CMake

```text
isa/
  CMakeLists.txt
  README.md
  include/isa/
    Types.h                 # 宽度、饱和
    Op.h                    # 操作码枚举 + OpFormat/OpClass + kOpDefs 表 + 助记符
    Instr.h                 # 32-bit 打包/拆字段（inline）
    Encode.h                # encode / decode / disasm
  src/
    Encode.cpp
```

```cmake
add_library(isa STATIC src/Encode.cpp)
target_include_directories(isa PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
```

`vm`：`target_link_libraries(vm PUBLIC isa)`；`compiler` 不链 `isa`。

---

## 实现说明

- **`Types.h`**：`Bool` = `uint8_t`、`Int` = `int16_t`、`Time` = `int64_t`（毫秒，理由见规范文）；`sat_add/sub/mul/div`（饱和规则见规范文）；`TypeTag`（0/1/2，`.stb` 常量表契约）
- **`Op.h`**：`enum Op : uint8_t`（数值即编码，与 `machine.toml` 强校验一致）；`OpFormat`（RR/RRR/IMM/SLOT/JMP/JC/CALL/CAL/NONE）与 `OpClass`（Plain/Instance）；34 条 `kOpDefs{ name, format, cls }`；`mnemonic/format/op_class` 查表
- **`Encode.cpp`**：`encode/decode` 往返 + `disasm`（按 format 表驱动，文本与规范文一致）

## 测试

`tests/isa_test`（链 `isa`）：饱和、操作码冻结值、指令打包、encode/decode 往返、disasm 文本、OpClass 分类。

## 验收

- `cmake --build` 过；`ctest` 过（`isa_roundtrip` 等 14 个用例全绿）
- `vm` 只 `#include <isa/...>`；`compiler` 不引用 `isa`
- 操作码有变：先改 `compiler/machine.toml` + 本目录 + 测试，再改两端