diff --git a/AGENTS.md b/AGENTS.md index 5d372a7..9e9d8bc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,12 @@ "C:/Program Files/Microsoft Visual Studio/18/Community/Common7/IDE/CommonExtensions/Microsoft/CMake/CMake/bin/cmake.exe" \ --build build --config Release ``` +* **`%synth` 的临时文件**:汇编器把生成的宏写到系统临时目录再 import,然后删掉。这台机器上 + 这一步**偶尔**会失败(`r8asm: cannot open 'C:\Users\...\Temp\xxx.synth.r8asm'`;同目录下 + `cmd` 能写、`r8forge` 不能,原因没查清,重跑一次可能就好了)。现在代码会退回到**当前工作 + 目录**重试,stderr 留一句 `<临时目录> is not writable, using `。看到这句不用管; + 看到 `cannot write the synthesised macro anywhere` 才是真坏了。`*.synth.r8asm` 已在 + `.gitignore` 里。 * 会话很长时传输容易失败,重要结论要落到 **commit message 和文件注释**里,别只留在对话里。 * **写结论之前先对虚拟机**:这个仓库最贵的一次事故就是虚拟机语义写错,然后在错的东西上 写了一整套"实测结论"(见「字节级运算」)。字节级结论必须能被 ROT-8-viz @@ -27,9 +33,10 @@ schannel 会报 `schannel: AcquireCredentialsHandle failed: SEC_E_NO_CREDENTIALS`, `fetch` / `push` 都得走 openssl 后端 —— 已经写在这个 repo 的 local config 里 (`git config http.sslBackend openssl`),正常 `git push` 就行。 - **`push` 还需要一次提权**:git 的凭证助手要开命名管道,沙箱(workspace-write)会拒绝, - 报 `sh.exe: fatal error - couldn't create signal pipe, Win32 error 5` + - `could not read Username`。`fetch` 不需要提权(仓库可匿名读)。 + 如果当前会话的沙箱是 workspace-write,`push` 还要一次提权:git 的凭证助手要开命名管道, + 沙箱会拒绝(`sh.exe: fatal error - couldn't create signal pipe, Win32 error 5` + + `could not read Username`);danger-full-access 下不需要。`fetch` 两种模式都不需要 + (仓库可匿名读)。 ## 构建与自检 @@ -49,6 +56,7 @@ r8forge asm/test.r8asm # 应 exit 0,1666 字符,7 r8forge_synth_test examples/full_add.r8asm # all eight combinations ok r8forge verify_raw_add_nc.r8asm # 4 cell 加法切片驱动 r8forge_byte_op_test # 字节级库:65536×4 + 512 全过,0.5 秒 +r8forge_macro_docs_test # 30 个宏的注释格式,全是 ok ``` `r8forge_byte_op_test` 是**唯一按返回值判断字节级对错的**;前三个只证明"汇编得出来"或 @@ -209,3 +217,8 @@ SPEC 第 136-150 行的标准宏前缀: * `%this` 表示"dp 当前所指的 cell"(`set_0`、`clb_bit_mov` 都这么写)。 * 新宏先按上表选前缀。套不上的(块级、自己管草稿 cell 的)就在注释里写清吃什么、留下什么。 +* **参数类型只用这五个**:`Cell`、`CellBit`、`Unit`、`UnitBit`、`Count`(纯数字,比如 + `step` 的重复次数)。注释块贴在 `%macro` 上方,或者贴在生成它的 `%synth` 块上方,都行。 +* `r8forge_macro_docs_test` 会检查 `asm/` 里每个 `%macro`:有没有注释块、 + `; Macro <名字>` 和实际宏名是否一致、参数条数是否等于 argc、类型是否在上面这五个里。 + 加完新宏跑一下,别让它的输出从全绿变红。 diff --git a/CMakeLists.txt b/CMakeLists.txt index a7db4a1..4154e6f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -35,6 +35,9 @@ add_executable(r8forge_tape_run tests/tape_run.cc) add_executable(r8forge_byte_op_test tests/byte_op_test.cc) target_link_libraries(r8forge_byte_op_test r8forge_core) +# Checks that every %macro in asm/ carries a doc comment in the house format. +add_executable(r8forge_macro_docs_test tests/macro_docs_test.cc) + add_executable(r8forge_cost_par tests/cost_par.cc) target_link_libraries(r8forge_cost_par r8forge_core) diff --git a/README.md b/README.md index 1b1c04a..ce5dfd2 100644 --- a/README.md +++ b/README.md @@ -381,6 +381,7 @@ cmake --build build --config Release build\Release\r8forge.exe asm\test.r8asm > test.rot8 build\Release\r8forge_synth_test.exe # 合成 + 跑虚拟机自检 build\Release\r8forge_byte_op_test.exe # 字节级库穷举:65536×4 + 512 全对 +build\Release\r8forge_macro_docs_test.exe # 30 个宏的注释格式 ``` `build/` 已经有生成器了,重编译时**别用 PATH 上的另一个 cmake**(版本不一致会重新配置, @@ -403,6 +404,7 @@ src/synth.cc 真值表 -> 搜索 tests/asm_test.cc 汇编器自检(纸带不变) tests/synth_test.cc 合成 + ROT-8 虚拟机自检 tests/byte_op_test.cc 字节级库穷举自检(65536×4 + 512) +tests/macro_docs_test.cc 宏注释格式自检(30 个宏) tests/tape_run.cc 第二个 ROT-8 解释器,直接跑 .rot8 交叉验证 asm/ 标准库与既有实现 examples/full_add.r8asm 汇编期合成全加器 diff --git a/asm/lib.r8asm b/asm/lib.r8asm index 3d7bea4..53b07ea 100644 --- a/asm/lib.r8asm +++ b/asm/lib.r8asm @@ -1,5 +1,5 @@ ; Macro step -; %1: step_count +; %1: Count step_count %macro step 1 %rep %1 stp @@ -8,7 +8,7 @@ %endmacro ; Macro back -; %1: back_count +; %1: Count back_count %macro back 1 %rep %1 btp @@ -143,7 +143,7 @@ copy copy_to_buffer_buf_1 %1 %endmacro ; Macro output -; %1: operand +; %1: Cell operand %macro output 1 .anchor before_output diff --git a/asm/raw_add_nc.r8asm b/asm/raw_add_nc.r8asm index 144e1a9..55691fa 100644 --- a/asm/raw_add_nc.r8asm +++ b/asm/raw_add_nc.r8asm @@ -6,12 +6,13 @@ ; 切片占 4 个 cell:A、B、进位、S。A、B 被吃掉(结束为 0),这和 bit_raw_add ; 不一样 —— 那个是保留 A、B 的,代价是多一个 Co 和一个 buf。 ; -; 两条实测结论(别忽略): -; 1. %synth 出来的程序只碰每个 cell 的低 K 位,高位不追踪; -; 2. set_0 展开成 [ - ],只对 0 和 1 收敛(5 会 5->4->5->4,0x80 永远不变)。 -; 所以喂进来的 cell 必须只放一位。正因如此,轮转式的字节级驱动配不了这个切片: -; 轮转要求 A、B 保留(每轮读它们的当前位),而合成的程序只会吃掉操作数 —— -; 把表改成"保留 A、B"之后 %synth 报 "no program up to 8 layers"。 +; 两条要知道的: +; 1. %synth 出来的程序只碰每个 cell 的低 K 位,高位不追踪 —— 这是个位级切片, +; 喂进来的 A、B、进位都必须是 0/1; +; 2. set_0 清的是最低位(`biz`/`rnz` 判 `cell & 1`,见 AGENTS),不会碰 S 的其余位。 +; +; 因为 A、B 被吃掉,它配不了轮转式的字节级驱动(那种驱动每轮还要读回操作数); +; 字节级的 `raw_add` 用的是保留 A、B 的 `bit_raw_add`(6 cell)。 ; Macro bit_raw_add_nc ; %1: CellBit A diff --git a/asm/raw_add_nc4.r8asm b/asm/raw_add_nc4.r8asm index 414af65..9f9d5c7 100644 --- a/asm/raw_add_nc4.r8asm +++ b/asm/raw_add_nc4.r8asm @@ -12,12 +12,22 @@ ; 只有 27,少一个 cell。代价是它只适用于"和不会溢出"的场合,而且调用者必须保证 ; 喂进来的 cell 里只有一位(见下)。 ; -; 已知约束(实测得出,别忽略): -; 1. 合成出来的程序只碰每个 cell 的低 K 位(K = 参与运算的输入位数),高位不追踪; -; 2. set_0 展开成 [ - ],只对 0 和 1 收敛(5 会 5->4->5->4 死循环,0x80 永远不变), -; 所以被 set_0 清的 cell 必须只放一位。 -; 因此这个切片只能用在"每个 cell 放一位"的场合;把和用 ror 轮转到第 7 位再喂进来 -; 会死循环。 +; 两条要知道的: +; 1. 合成出来的程序只碰每个 cell 的低 K 位(K = 参与运算的输入位数),高位不追踪 —— +; 这是个位级切片,喂进来的 A、B、进位都必须是 0/1; +; 2. set_0 清的是最低位(`biz`/`rnz` 判的是 `cell & 1`,见 AGENTS),所以 S 里的 +; 其余位不会被它动。 +; A、B 被吃掉,所以它配不了轮转式的字节级驱动 —— 那种驱动每轮还要读回操作数。 +; 字节级的 `raw_add` 用的是保留 A、B 的 `bit_raw_add`(6 cell)。 + +; Macro bit_add_nc4 +; %1: CellBit A +; %2: CellBit B +; %3: CellBit Ci +; %4: CellBit S +; +; 和 asm/raw_add_nc.r8asm 里的 bit_raw_add_nc 是同一张表(4 cell、flat 代价 27), +; 区别只有包装宏的名字。目前仓库里没有引用这个文件。 %synth bit_add_nc4_synth params 4 stat 0 8 8 4 8 4 4 12 0 8 8 4 8 4 4 12 diff --git a/asm/raw_and.r8asm b/asm/raw_and.r8asm index 1d183cc..fc3f676 100644 --- a/asm/raw_and.r8asm +++ b/asm/raw_and.r8asm @@ -53,7 +53,7 @@ rnz %endmacro -; Macro bit_and +; Macro bit_raw_and ; %1: CellBit arg1 ; %2: CellBit arg2 ; %3: CellBit ans @@ -74,7 +74,7 @@ rnz %endmacro -; Macro and +; Macro raw_and ; %1: Cell arg1 ; %2: Cell arg2 ; %3: Cell ans diff --git a/asm/raw_xor.r8asm b/asm/raw_xor.r8asm index ccfccf3..5ae8e76 100644 --- a/asm/raw_xor.r8asm +++ b/asm/raw_xor.r8asm @@ -61,8 +61,8 @@ ; Macro raw_xor -; %1: Unit arg1 -; %2: Unit arg2 +; %1: Cell arg1 +; %2: Cell arg2 ; %3: Cell ans ; %4: CellBit tmp %macro raw_xor 4 diff --git a/src/r8asm.cc b/src/r8asm.cc index 52a4f5c..39f72fb 100644 --- a/src/r8asm.cc +++ b/src/r8asm.cc @@ -534,26 +534,63 @@ r8asm::ast_node r8asm::parse(const token_stream &stream) { // then goes through the normal, well tested expansion path instead // of being spliced by hand. set_1 is spelled out (set_0 + flb) so // the generated file needs nothing from lib.r8asm. - const std::string path = (std::filesystem::temp_directory_path() / - (name + ".synth.r8asm")) - .string(); - std::ofstream file(path); - file << "%macro " << name << " " << spec.params << "\n"; + // + // It goes to the system temp directory, and to the working directory + // if that one cannot be written: a sandbox may allow a process to + // write only inside its own tree, and then temp_directory_path() + // happily returns a path whose open() fails. + std::ostringstream body; + body << "%macro " << name << " " << spec.params << "\n"; for (const auto &i : prog) { - file << ".tp %" << i[0] + 1 << "\nbiz\n"; + body << ".tp %" << i[0] + 1 << "\nbiz\n"; for (int b = 0; b < 8; b++) if (i[1] & (1 << b)) { - file << ".tp %" << b + 1 << "\n"; + body << ".tp %" << b + 1 << "\n"; if (i[2]) - file << "biz\nflb\nrnz\n"; // set_0 - file << "flb\n"; + body << "biz\nflb\nrnz\n"; // set_0 + body << "flb\n"; } - file << ".tp %" << i[0] + 1 << "\nflb\nrnz\n"; + body << ".tp %" << i[0] + 1 << "\nflb\nrnz\n"; + } + body << "%endmacro\n"; + + std::vector dirs; + std::error_code ec; + const std::filesystem::path temp_dir = + std::filesystem::temp_directory_path(ec); + if (!ec) + dirs.push_back(temp_dir); + const std::filesystem::path work_dir = + std::filesystem::current_path(ec); + if (!ec) + dirs.push_back(work_dir); + + std::string path; + for (size_t d = 0; d < dirs.size(); d++) { + const std::filesystem::path candidate = + dirs[d] / (name + ".synth.r8asm"); + std::ofstream file(candidate, std::ios::binary); + if (!file) + continue; + file << body.str(); + file.close(); + if (!file) + continue; + if (d > 0) + std::cerr << "r8asm: %synth " << name << ": " + << dirs.front().string() + << " is not writable, using " << dirs[d].string() + << std::endl; + path = candidate.string(); + break; + } + if (path.empty()) { + main_tree.fail("%synth '" + name + + "': cannot write the synthesised macro anywhere"); + } else { + import_file(path, main_tree.CELL_SIZE); + std::remove(path.c_str()); } - file << "%endmacro\n"; - file.close(); - import_file(path, main_tree.CELL_SIZE); - std::remove(path.c_str()); } } break; default: diff --git a/tests/macro_docs_test.cc b/tests/macro_docs_test.cc new file mode 100644 index 0000000..71934eb --- /dev/null +++ b/tests/macro_docs_test.cc @@ -0,0 +1,171 @@ +// Checks that every %macro in the standard library carries a doc comment in the +// house format: +// +// ; Macro bit_raw_add +// ; %1: CellBit A +// ; %2: CellBit B +// ... +// +// ; %this: CellBit operand (only for macros that work on the current cell) +// +// The comment block may sit directly above the %macro, or above the %synth +// block that generates the macro body (the library does the latter whenever the +// body is synthesised) -- this runs often enough that a missing or stale block +// is worth a machine check rather than a review. +// +// r8forge_macro_docs_test [asm dir] default: asm +// +// Parameter types are the ones the library uses: Cell, CellBit, Unit, UnitBit +// and Count (a plain number, for things like step's repeat count). +#include +#include +#include +#include +#include +#include +#include +#include + +namespace { + +struct block { + size_t first = 0; // line index of the first ';' line + size_t last = 0; // line index of the last ';' line +}; + +bool is_comment(const std::string &line) { + const size_t at = line.find_first_not_of(" \t"); + return at != std::string::npos && line[at] == ';'; +} + +const std::vector TYPES = {"Cell", "CellBit", "Unit", "UnitBit", + "Count"}; + +std::vector read_lines(const std::filesystem::path &path) { + std::vector lines; + std::ifstream in(path); + std::string line; + while (std::getline(in, line)) { + if (!line.empty() && line.back() == '\r') + line.pop_back(); + lines.push_back(line); + } + return lines; +} + +} // namespace + +int main(int argc, char **argv) { + const std::filesystem::path dir = argc > 1 ? argv[1] : "asm"; + + std::vector files; + std::error_code ec; + for (const auto &entry : std::filesystem::directory_iterator(dir, ec)) { + if (entry.path().extension() == ".r8asm") + files.push_back(entry.path()); + } + if (ec || files.empty()) { + std::cerr << "cannot read " << dir << " (" << ec.message() << ")\n"; + return 2; + } + std::sort(files.begin(), files.end()); + + const std::regex macro_re(R"(^[ \t]*%macro[ \t]+([A-Za-z_][A-Za-z0-9_]*)[ \t]+([0-9]+))"); + const std::regex head_re(R"(^[ \t]*;[ \t]*Macro[ \t]+(\S+)[ \t]*$)"); + const std::regex param_re( + R"(^[ \t]*;[ \t]*%([0-9]+):[ \t]*(\S+)[ \t]*(\S+)[ \t]*$)"); + + size_t macros = 0; + std::vector problems; + + for (const auto &file : files) { + const std::vector lines = read_lines(file); + + // every maximal run of ';' lines + std::vector blocks; + for (size_t i = 0; i < lines.size();) { + if (!is_comment(lines[i])) { + i++; + continue; + } + block b; + b.first = i; + while (i < lines.size() && is_comment(lines[i])) + i++; + b.last = i - 1; + blocks.push_back(b); + } + + for (size_t m = 0; m < lines.size(); m++) { + std::smatch match; + if (!std::regex_search(lines[m], match, macro_re)) + continue; + const std::string name = match[1]; + const size_t argc = std::stoul(match[2]); + macros++; + + const std::string where = + file.filename().string() + ":" + std::to_string(m + 1) + ": " + name; + + // the closest block that ends before this %macro + const block *doc = nullptr; + for (const block &b : blocks) + if (b.last < m) + doc = &b; + if (doc == nullptr) { + problems.push_back(where + ": no doc comment"); + continue; + } + + std::string doc_name; + size_t documented = 0; + bool bad_shape = false; + for (size_t i = doc->first; i <= doc->last; i++) { + std::smatch m2; + if (std::regex_search(lines[i], m2, head_re)) + doc_name = m2[1]; + if (!std::regex_search(lines[i], m2, param_re)) + continue; + documented++; + const std::string type = m2[2]; + if (std::find(TYPES.begin(), TYPES.end(), type) == TYPES.end()) { + problems.push_back(where + ":" + std::to_string(i + 1) + + ": unknown parameter type '" + type + "'"); + bad_shape = true; + } + if (m2[3].str().empty()) { + problems.push_back(where + ":" + std::to_string(i + 1) + + ": parameter has no name"); + bad_shape = true; + } + } + if (doc_name.empty()) { + problems.push_back(where + ": the comment block above has no " + "'; Macro ' line"); + continue; + } + if (doc_name != name) { + problems.push_back(where + ": doc says Macro " + doc_name); + continue; + } + if (documented != argc) { + problems.push_back(where + ": " + std::to_string(argc) + " parameters, " + + std::to_string(documented) + + " documented"); + continue; + } + (void)bad_shape; + } + std::cout << file.filename().string() << ": ok\n"; + } + + std::cout << macros << " macros in " << files.size() << " files\n"; + if (problems.empty()) { + std::cout << "all documented in the house format\n"; + return 0; + } + std::cout << problems.size() << " problem(s):\n"; + for (const std::string &p : problems) + std::cout << " " << p << "\n"; + return 1; +}