Tidy the standard library's macro docs, and check them by machine

Audited all 30 %macro in asm/.  The format was already followed almost
everywhere -- the doc block sits above the %macro, or above the %synth block
that generates its body -- but four things were wrong:

  raw_and.r8asm  the two doc blocks still carried the old names (bit_and, and)
  raw_xor.r8asm  raw_xor's first two parameters were typed Unit, not Cell
  lib.r8asm      step / back / output had no type at all ("%1: step_count")

and two files still repeated the retracted claim that set_0 only converges on 0
and 1 (raw_add_nc.r8asm, raw_add_nc4.r8asm).  Those now say what set_0 really
does -- it clears the low bit -- and stay on the point that matters for a bit
level slice: A, B and the carry must be single bits because the searched
program only tracks the low K bits.

Parameter types are now a closed set: Cell, CellBit, Unit, UnitBit, Count
(Count is for step/back's repeat count).  It is written down in AGENTS.md
together with the format, so the next macro has something to copy.

New r8forge_macro_docs_test checks the format instead of trusting review: a doc
block must exist, its ";   Macro <name>" line must match the macro, the number
of documented parameters must equal argc, and every type must be one of the
five.  Negative tested by deleting a parameter line and by renaming a block --
it reports both and exits 1.

Also fixes a real annoyance found while running the checks: %synth writes its
generated macro to the system temp directory and imports it.  That write fails
intermittently on this machine (same directory, cmd can write, r8forge cannot;
cause unknown), which turned every assembly into "cannot open ...synth.r8asm".
The body is now built in memory and written to the temp directory or, if that
open fails, to the working directory, with one stderr line saying so.

Full suite green: test.r8asm 1666 characters, full_add 8/8, verify_raw_add_nc,
byte_op_test 65536x4 + 512, macro_docs_test 30/30, fibonacci prints its ten
numbers.
This commit is contained in:
dsh committed 2026-11-07 00:23:28 +08:00
1 parent 0fa30baf47
commit 56ea288cd6
10 files changed
+273 -36

No files matched your search

+16 -3
View File
@@ -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 <cwd>`。看到这句不用管;
看到 `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、类型是否在上面这五个里。
加完新宏跑一下,别让它的输出从全绿变红。
+3
View File
@@ -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)
+2
View File
@@ -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 汇编期合成全加器
+3 -3
View File
@@ -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
+7 -6
View File
@@ -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
+16 -6
View File
@@ -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
+2 -2
View File
@@ -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
+2 -2
View File
@@ -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
+51 -14
View File
@@ -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<std::filesystem::path> 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:
+171
View File
@@ -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 <algorithm>
#include <cstdio>
#include <filesystem>
#include <fstream>
#include <iostream>
#include <regex>
#include <string>
#include <vector>
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<std::string> TYPES = {"Cell", "CellBit", "Unit", "UnitBit",
"Count"};
std::vector<std::string> read_lines(const std::filesystem::path &path) {
std::vector<std::string> 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<std::filesystem::path> 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<std::string> problems;
for (const auto &file : files) {
const std::vector<std::string> lines = read_lines(file);
// every maximal run of ';' lines
std::vector<block> 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 <name>' 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;
}