【工具篇·番外】跨语言生态的主权回收：基于 ISA 说明书的 4-bit 双向汇编系统全线封顶

前言：工具链的跨语言赤字与生态主权回收

在上一篇《【控制篇·终章】时序的异步革命》中，我们通过无栈现场保护墓碑区与 W1C 中断控制器，成功在 4-bit 宇宙里引爆了异步时序的工业革命。然而，当我们站在 4KB 全局编址的广阔疆域上，准备真正向《俄罗斯方块》的应用层业务发起总攻时，一个历史遗留的工程赤字却死死卡住了脖子 ------ 我们的工具链（Compiler）依然在靠外挂的 Python 脚本两遍扫描（2-Pass）来苟延残喘。

在旧的生态中，仿真内核使用的是 C++，而汇编器使用的是 Python。当我们在接下来的应用层合围中，因为 1280 字节 ROM 的断头台限制，需要紧急追加如长腿加载（LDA）、自增减（INC/DEC）或开闭中断（STI/CLI）等新指令来压榨空间时，我们必须两头动刀：改完 Python 脚本，生成十六进制，再肉肉地粘贴回 C++ 仿真内存。这种跨语言、硬编码割裂的状态，在工业级仿真器开发中被称为"生态断层"。

真正的数字帝国，必须收回编译器与逆向解构的绝对主权。

本期番外篇，我们彻底斩断外部 Python 依赖，直接在 Qt Creator 宿主内用纯 C++（Standard C++11/17）重写编译基建。通过引入一纸外部 isa.txt（指令集架构说明书），我们建立了一套完全数据驱动的双向编译全家桶（正向 2-Pass 汇编器 + 逆向反汇编引擎）。从此，只要修改一纸文本，整台机器就能在正反两个次元无缝自我解构！

📜 第一章：数据驱动：一纸 isa.txt 的物理硬件描述法典

要让编译器和反汇编器变成不与具体机器码绑死的多态通用引擎，第一步就是将指令集的硬编码彻底抽离。我们为此建立了一套极简但极其刚性的外部 ISA 配置文件 ------ isa.txt。未来你想增加任何新指令，完全不需要改动并重新编译汇编器本身，只需要在这张规格表里加一行，编译器和反汇编器瞬间就能原地学会新语法：

; =========================================================================
; 4-BIT PROCESSING UNIT: INSTRUCTION SET ARCHITECTURE SPEC (DATA-DRIVEN)
; =========================================================================
; 助记符    基本机器码   操作数类型      指令总长度(1字节Opcode+长腿Nibble数)
NOP        0x01        NONE           1
HALT       0x03        NONE           1
PUSH       0x09        NONE           1
POP        0x0A        NONE           1
RET        0x0C        NONE           1
RETI       0x1D        NONE           1

MOV        0x10        REG_REG        1
LDI        0x20        REG_IMM        1
OR         0x30        NONE           1
XOR        0x40        NONE           1
ADD        0x05        NONE           1
SUB        0x06        NONE           1
STA        0x08        LONG_ADDR      4
AND        0x0A        NONE           1
JZ         0x0D        LONG_ADDR      4
JMP        0x0F        LONG_ADDR      4

💡 核心设计精髓：位置无关映射与自适应尺寸感知

在这张规格表里，指令名、16进制基准码和它的操作数类型（OperandType）、物理占用空间（Size）被完全参数化。

• 正向汇编（Assembler）：在 Pass 1 阶段无需认得指令细节，仅通过 LONG_ADDR 标记就能瞬间动态感知这条指令会吃掉 4 个内存单元，从而完美对齐位置计数器（Location Counter）和符号标签（Label）。
• 反汇编引擎（Disassembler）：在遇到复杂的多字节长腿指令（如 CALL）时，通过 Size=4 属性，能瞬间知道在取指后，必须强制向下连续吞噬 3 个半字节（Nibble）才能完美缝合出原始的 12 位长腿目标跳转地址。

🛠️ 第二章：正向熔炼：纯 C++ 2-Pass 汇编器核心实现

我们在 C++ 的 Assembler 类中利用标准容器 std::map 动态建立查找地图。在 2-Pass 的正向编译控制流中，我们利用高级分词工具（Tokenize），自动过滤掉逗号、方括号、冒号等物理语法噪声，并无缝支持字节资产批量烧录定义伪指令 .db，用以冷冻《俄罗斯方块》的点阵字模：

#ifndef ASSEMBLER_H
#define ASSEMBLER_H

#include <string>
#include <vector>
#include <map>
#include <cstdint>

enum class OperandType { NONE, REG_REG, REG_IMM, LONG_ADDR };

struct InstructionSpec {
    std::uint8_t baseOpcode; 
    OperandType type;        
    std::uint8_t size;       
};

class Assembler {
private:
    std::map<std::string, std::uint16_t> symbolTable;
    std::map<std::string, InstructionSpec> isaTable;
    std::map<std::uint8_t, std::pair<std::string, InstructionSpec>> inverseIsaTable;

    std::string cleanLine(const std::string& line);
    std::vector<std::string> tokenize(const std::string& line);
    std::uint16_t parseLiteral(const std::string& token);

public:
    Assembler() = default;
    ~Assembler() = default;

    bool loadISA(const std::string& configFilePath);
    std::vector<std::uint8_t> compile(const std::string& sourceCode);
    std::string disassemble(const std::vector<std::uint8_t>& binaryImage, std::uint16_t startAddr, std::uint16_t length);
};

#endif // ASSEMBLER_H

目前篇幅有限，先把头文件展示出来，欢迎大家评论，具体代码整理后我会上传至github/gitee等代码平台。

🔍 第三章 : 逆向反合围与反汇编引擎实现

反汇编（Disassembly）是本期番外篇最性感的章节。在算力贫血、位宽极窄的 4-bit 机器码镜像中，数据和代码在 4KB 的大平原上是完全平铺的。反汇编引擎必须像一个深海潜望镜，通过高位掩码匹配算法与长腿吞噬时序实现机器码的物理还原：

std::string Assembler::disassemble(const std::vector<std::uint8_t>& binaryImage, std::uint16_t startAddr, std::uint16_t length) {
    std::stringstream out; std::uint16_t pc = startAddr;
    std::uint16_t endAddr = std::min(static_cast<size_t>(startAddr + length), binaryImage.size());

    while (pc < endAddr) {
        std::uint8_t opcode = binaryImage[pc];
        std::uint8_t op = opcode & 0xF0; 
        std::uint8_t lookupKey = (op == 0x10 || op == 0x20) ? op : opcode;

        out << "0x" << std::hex << std::uppercase << std::setw(4) << std::setfill('0') << pc << ": ";
        if (inverseIsaTable.find(lookupKey) != inverseIsaTable.end()) {
            auto match = inverseIsaTable[lookupKey]; std::string mnemonic = match.first; InstructionSpec spec = match.second;
            switch (spec.type) {
                case OperandType::NONE: out << mnemonic; pc += spec.size; break;
                case OperandType::REG_IMM: out << mnemonic << " A, #" << std::hex << (int)(opcode & 0x0F); pc += spec.size; break;
                case OperandType::REG_REG: {
                    std::uint8_t p = opcode & 0x0F;
                    auto reg = [](uint8_t c) { return (c==0)?"A":(c==1)?"B":(c==2)?"X":"Y"; };
                    out << mnemonic << " " << reg((p >> 2) & 0x03) << ", " << reg(p & 0x03);
                    pc += spec.size; break;
                }
                case OperandType::LONG_ADDR: {
                    if (pc + 3 < binaryImage.size()) {
                        std::uint16_t targetAddr = ((binaryImage[pc+1]&0x0F)<<8) | ((binaryImage[pc+2]&0x0F)<<4) | (binaryImage[pc+3]&0x0F);
                        out << mnemonic << " 0x" << std::hex << std::uppercase << std::setw(4) << std::setfill('0') << targetAddr;
                    } else out << mnemonic << " [OVERFLOW]";
                    pc += spec.size; break;
                }
            }
        } else {
            out << ".db 0x" << std::hex << std::uppercase << std::setw(2) << std::setfill('0') << (int)opcode; pc += 1;
        }
        out << "\n";
    }
    return out.str();
}

// 📑 基础分词辅助工具实现
std::string Assembler::cleanLine(const std::string& line) {
    std::string s = line; size_t p = s.find(';'); if (p != std::string::npos) s = s.substr(0, p);
    s.erase(s.begin(), std::find_if(s.begin(), s.end(), [](unsigned char c) { return !std::isspace(c); }));
    s.erase(std::find_if(s.rbegin(), s.rend(), [](unsigned char c) { return !std::isspace(c); }).base(), s.end());
    return s;
}
std::vector<std::string> Assembler::tokenize(const std::string& line) {
    std::vector<std::string> tokens; std::string current;
    for (char ch : line) {
        if (std::isspace(ch) || ch == ',' || ch == '[' || ch == ']') {
            if (!current.empty()) { tokens.push_back(current); current.clear(); }
        } else if (ch == ':') {
            if (!current.empty()) { tokens.push_back(current); current.clear(); }
            tokens.push_back(":");
        } else current.push_back(ch);
    }
    if (!current.empty()) tokens.push_back(current);
    return tokens;
}
std::uint16_t Assembler::parseLiteral(const std::string& token) {
    std::string t = token; if (!t.empty() && t[0] == '#') t = t.substr(1);
    try { if (t.rfind("0x", 0) == 0 || t.rfind("0X", 0) == 0) return static_cast<std::uint16_t>(std::stoul(t, nullptr, 16));
          return static_cast<std::uint16_t>(std::stoul(t, nullptr, 10)); } catch (...) { return 0; }
}

这是反汇编的核心实现，属于比较初始的逻辑，优化后我还会继续push代码

🎨 第四章：完全体合围：Mini-DEBUG 迷你调试器测试点火

在 Qt Creator 的影子构建（Shadow Build）生态下，为了彻底斩断资产由于工作路径偏移导致的读取失败，我们在 .pro 文件中挂载了 QMAKE_POST_LINK 跨平台全自动资产走私通道。并在 main.cpp 一开局顶格实例化 QCoreApplication app(argc, argv); 对象，从而通过 applicationDirPath() + "/isa.txt" 抓出坚如磐石的绝对磁盘路径。

最后，我们将正向汇编、反向解构与全量寄存器监控面板（A、B、X、Y、SP、PC）完美接入 miniDebug。以下是正式敲定、完美闭环的 main.cpp 完全体源码：

#include <iostream>
#include <iomanip>
#include <string>
#include <vector>
#include <QCoreApplication>
#include "includes/emulator.h"
#include "includes/assembler.h"

void dumpToConsole(Emulator* emu, uint16_t startAddr, uint16_t len) {
    uint16_t alignedStart = (startAddr / 16) * 16;
    uint16_t alignedEnd = ((startAddr + len + 15) / 16) * 16;
    auto data = emu->readMemoryBlock(alignedStart, alignedEnd - alignedStart);

    std::cout << "ADDR   | 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F | ASCII" << std::endl;
    std::cout << "-------+------------------------------------------------+--------" << std::endl;
    for (size_t i = 0; i < data.size(); i += 16) {
        std::cout << "0x" << std::hex << std::uppercase << std::setw(4) << std::setfill('0') << (alignedStart + i) << " | ";
        for (size_t j = 0; j < 16; ++j) std::cout << std::setw(2) << std::setfill('0') << (int)data[i + j] << " ";
        std::cout << "| ";
        for (size_t j = 0; j < 16; ++j) {
            uint8_t ch = data[i + j];
            std::cout << (std::isprint(ch) ? static_cast<char>(ch) : '.');
        }
        std::cout << std::endl;
    }
}

void printRegisters(Emulator* emu) {
    std::cout << "A=" << std::hex << std::uppercase << (int)emu->getRegA() << "  "
              << "B=" << (int)emu->getRegB() << "  "
              << "X=" << (int)emu->getRegX() << "  "
              << "Y=" << (int)emu->getRegY() << "  "
              << "SP=" << std::setw(4) << std::setfill('0') << (int)emu->getSP() << "  "
              << "PC=" << std::setw(4) << std::setfill('0') << (int)emu->getPC() << "  "
              << "FLAGS=" << emu->getFlagsString() << " (0x" << (int)emu->getFlags() << ")" << std::endl;
}

int main(int argc, char* argv[]) {
    [[maybe_unused]] QCoreApplication app(argc, argv);
    std::cout << "Starting 4-Bit Emulator Kernel & Compiler Engine..." << std::endl;
    
    Emulator emu; Assembler as;
    QString isaAbsPath = QCoreApplication::applicationDirPath() + "/isa.txt";
    if (!as.loadISA(isaAbsPath.toStdString())) {
        std::cerr << "Fatal Error: Missing isa.txt at " << isaAbsPath.toStdString() << std::endl; return -1;
    }

    // 🆕 极客震撼：直接在 C++ 内部用纯文本标签人类语言热点火！
    std::string tetrisMockCode = 
        ".org 0x000\n"
        "START:\n"
        "    CALL SUB_ROUTINE\n"
        "    HALT\n"
        ".org 0x100\n"
        "SUB_ROUTINE:\n"
        "    LDI A, 7\n"
        "    MOV B, A\n"
        "    RET\n";

    std::vector<uint8_t> firmware = as.compile(tetrisMockCode);
    emu.loadProgram(firmware.data(), firmware.size());

    printRegisters(&emu);
    std::cout << "- " << std::flush;

    std::string line;
    while (std::getline(std::cin, line)) {
        if (line.empty()) { std::cout << "- " << std::flush; continue; }
        char cmd = std::tolower(line[0]);
        std::stringstream ss(line.substr(1));

        if (cmd == 'q') { std::cout << "Exiting Debugger." << std::endl; break; }
        switch (cmd) {
            case 'r': printRegisters(&emu); break;
            case 't': emu.tick(); printRegisters(&emu); break;
            case 'd': {
                uint32_t addr = emu.getPC(), len = 16;
                if (ss >> std::hex >> addr) ss >> std::hex >> len;
                dumpToConsole(&emu, addr, len); break;
            }
            case 'e': {
                uint32_t addr = 0, data = 0;
                if (ss >> std::hex >> addr >> std::hex >> data) emu.writeMemory(addr, data);
                break;
            }
            case 'i': {
                uint32_t lineNo = 0; ss >> std::hex >> lineNo;
                emu.triggerHardwareInterrupt(lineNo & 0x03); break;
            }
            case 'u': { // 逆向工程：U 命令实时调用反汇编引擎反查当前 ROM
                uint32_t addr = emu.getPC(), len = 16;
                if (ss >> std::hex >> addr) ss >> std::hex >> len;
                std::cout << as.disassemble(firmware, addr, len) << std::endl; break;
            }
            case 'g': {
                while (!(emu.getFlags() & 0x08)) emu.tick();
                std::cout << "Halt encountered." << std::endl; printRegisters(&emu); break;
            }
            default: std::cout << "Unknown command." << std::endl; break;
        }
        std::cout << "- " << std::flush;
    }
    return 0;
}

这是Mini-Debug的核心实现，属于比较初始的逻辑，优化后我还会继续push代码

🏁 第五章：工程总结与下期硬核预告

本期番外篇通过对 ISA 数据驱动架构的完全解耦，我们在纯 C++ 环境下封顶了正反向全家桶基建，彻底回收了工具链的主权。我们终于拥有了一座可以无限扩容的代码工厂。

基础设施已完全宣告大获全胜，战术地图已经无缝接轨。

从下一章开始，我们将正式进入整机大总攻。我们将利用这套刚刚打造好的全自动动态工具链，去实现那些《俄罗斯方块》中寸土必争的剩余指令模拟器实现，揭开游戏引擎正式合围的序幕！

下期预告：《【应用篇·开篇】压榨最后的半字节：长腿加载 LDA 指令的模拟器实现与只读字模动态提取时序》