Add a mode switch and a getting-started section

%synth used to always run both searches, so every assembly of the full adder
sat there for twenty minutes.  A block can now say 'mode layers' to stop after
the layer search (7.7 seconds) or 'mode tape' (the default) to pay for the
shortest tape.  examples/full_add_layers.r8asm is the fast one, 95 characters
and still checked on the machine.

The lexer also no longer chokes on a UTF-8 BOM.  Every Windows editor writes
one, and the first token came out as a garbage prefix, which crashed the
assembler with an access violation rather than saying anything useful.

README grew a getting-started walkthrough: build, a complete adder.r8asm, what
the two stderr lines mean, how to drop a synth block into a library, and the
three things that bite (inputs first, don't call them in/out, map length).
This commit is contained in:
dsh committed 2026-11-06 10:14:58 +08:00
1 parent 346cbdc6e4
commit 6f2ecf0e22
5 files changed
+129 -12

No files matched your search

+71
View File
@@ -60,6 +60,77 @@ all eight combinations ok
注意 `inputs` / `outputs` 不能写成 `in` / `out`:`out` 和 ROT-8 助记符撞了,词法会先认成
`rot8_out`,整个 block 解析错位。
## 从零开始
```sh
cmake -S . -B build -G "Visual Studio 18 2026" -A x64 # 或者用 Ninja / Makefile
cmake --build build --config Release
```
写一个 `adder.r8asm`:
```asm
%include "asm/lib.r8asm"
%synth fulladd
params 6
inputs %1 %2 %3 ; 3 个输入位,必须是最前面的参数
outputs %4 %5 ; 2 个输出位
map 0 1 1 2 1 2 2 3 ; 8 个输入组合各自的输出位取值
mode tape ; tape = 最短纸带(默认),layers = 只求层数最少(快)
%endsynth
.var A 0
.var B 1
.var Ci 2
.var S 3
.var Co 4
.var T 5
fulladd A B Ci S Co T
output S
output Co
```
汇编:
```sh
build/Release/r8forge adder.r8asm > adder.rot8
```
stderr 上会告诉你它查到了什么,stdout 就是纸带:
```
r8asm: %synth fulladd: 5 layers (shortest), 20388515 states, 7.7s
r8asm: %synth fulladd: tape cost 75 in 6 blocks (layer answer was 82), 415041596 states, 1280s
```
`mode layers` 只跑第一行(7.7 秒),`mode tape`(默认)会接着跑第二行。迭代的时候用
`layers`,要发布再切回 `tape`,否则每次汇编都要等 20 分钟。
### 放进自己的库里
`%synth` 块定义完就是一个普通宏,所以在库里写一次即可:
```asm
; asm/my_adder.r8asm
%synth bit_add
params 6
inputs %1 %2 %3
outputs %4 %5
map 0 1 1 2 1 2 2 3
%endsynth
```
调用点和普通宏调用一样:`bit_add A B Ci S Co tmp` —— 替换掉现有实现就是改这一行。
### 三条要注意的
1. **输入参数必须排在最前面**(`%1..%K`)。搜索器把真值表索引直接当输入值,靠的就是这个顺序。
2. **`inputs` / `outputs` 不能写成 `in` / `out`**:`out` 和 ROT-8 助记符撞了,词法会先认成
`rot8_out`。
3. `map` 的长度必须是 `2^输入个数`,每一项是那个组合下输出位拼成的整数(bit0 = 第一个输出)。
## 实现方式
`%synth` 在 `parse()` 里被读成一张真值表,随即调用搜索器;得到的块序列写成
+20
View File
@@ -0,0 +1,20 @@
%include "asm/lib.r8asm"
%synth fulladd_fast
params 6
inputs %1 %2 %3
outputs %4 %5
map 0 1 1 2 1 2 2 3
mode layers
%endsynth
.var A 0
.var B 1
.var Ci 2
.var S 3
.var Co 4
.var T 5
fulladd_fast A B Ci S Co T
output S
output Co
+3 -1
View File
@@ -18,7 +18,8 @@
std::vector<std::array<int, 3>>
r8asm_synth_program(int params, const std::vector<int> &in,
const std::vector<int> &out, const std::vector<int> &map,
const std::string &name, const std::vector<int> &layout);
const std::string &name, const std::vector<int> &layout,
int mode);
class r8asm {
using data = int16_t;
@@ -123,6 +124,7 @@ private:
std::vector<int> out; // param index per output bit, bit 0 first
std::vector<int> map; // 2^|in| entries: output bits of that input
std::vector<int> layout; // optional: cell address of each parameter
int mode = 0; // 0 = shortest tape, 1 = fewest layers only
};
private:
+19 -1
View File
@@ -464,6 +464,14 @@ r8asm::ast_node r8asm::parse(const token_stream &stream) {
std::vector<int> &dst = (kw == "inputs") ? spec.in : spec.out;
for (size_t i = 1; i < it->tokens.size(); i++)
dst.push_back(std::stoi(it->tokens[i].value) - 1);
} else if (kw == "mode") {
const std::string &m = it->tokens[1].value;
if (m == "layers")
spec.mode = 1;
else if (m == "tape")
spec.mode = 0;
else
main_tree.fail("unknown mode '" + m + "'");
} else if (kw == "layout") {
for (size_t i = 1; i < it->tokens.size(); i++)
spec.layout.push_back(std::stoi(it->tokens[i].value));
@@ -475,7 +483,8 @@ r8asm::ast_node r8asm::parse(const token_stream &stream) {
}
}
auto prog = r8asm_synth_program(spec.params, spec.in, spec.out,
spec.map, name, spec.layout);
spec.map, name, spec.layout,
spec.mode);
if (prog.empty()) {
main_tree.fail("%synth '" + name + "': nothing emitted");
} else {
@@ -727,7 +736,16 @@ r8asm::token_stream::lex(const std::string &char_stream) {
{"&", "op_and"}, {"|", "op_or"}, {"~", "op_not"}, {"-", "op_sub"},
};
bool first_line = true;
while (std::getline(iss, str_buffer)) {
// a UTF-8 BOM would otherwise end up glued to the first token and every
// editor on Windows writes one
if (first_line && str_buffer.size() >= 3 &&
(unsigned char)str_buffer[0] == 0xEF &&
(unsigned char)str_buffer[1] == 0xBB &&
(unsigned char)str_buffer[2] == 0xBF)
str_buffer.erase(0, 3);
first_line = false;
std::vector<token> token_buffer = {};
bool start_of_line = true;
bool lquote_appeared = false;
+16 -10
View File
@@ -12,7 +12,7 @@ template <int P>
std::vector<std::array<int, 3>>
r8asm_synth_run(const std::vector<int> &in, const std::vector<int> &out,
const std::vector<int> &map, const std::string &name,
const std::vector<int> &layout) {
const std::vector<int> &layout, int mode) {
using V = r8veritas<P>;
V v;
v.initialize_nicknames();
@@ -50,6 +50,12 @@ r8asm_synth_run(const std::vector<int> &in, const std::vector<int> &out,
<< " layers" << (layers.proven_optimal ? " (shortest)" : "")
<< ", " << layers.states << " states, " << layers.seconds << "s\n";
if (mode == 1) { // fewest layers only: skip the tape search
for (const auto &i : layers.program)
out_ins.push_back({int(i.sacrifice), int(i.mask), int(i.or_mode)});
return out_ins;
}
// 2) shortest tape -- exact, so it stops as soon as the goal is popped
typename V::cost_options copt;
copt.max_states = 450'000'000;
@@ -97,7 +103,7 @@ std::vector<std::array<int, 3>>
r8asm_synth_program(int params, const std::vector<int> &in,
const std::vector<int> &out, const std::vector<int> &map,
const std::string &name,
const std::vector<int> &layout) {
const std::vector<int> &layout, int mode) {
if (params < 1 || params > 8) {
std::cerr << "r8asm: %synth " << name << ": supports 1..8 parameters\n";
return {};
@@ -115,21 +121,21 @@ r8asm_synth_program(int params, const std::vector<int> &in,
}
switch (params) {
case 1:
return r8asm_synth_run<1>(in, out, map, name, layout);
return r8asm_synth_run<1>(in, out, map, name, layout, mode);
case 2:
return r8asm_synth_run<2>(in, out, map, name, layout);
return r8asm_synth_run<2>(in, out, map, name, layout, mode);
case 3:
return r8asm_synth_run<3>(in, out, map, name, layout);
return r8asm_synth_run<3>(in, out, map, name, layout, mode);
case 4:
return r8asm_synth_run<4>(in, out, map, name, layout);
return r8asm_synth_run<4>(in, out, map, name, layout, mode);
case 5:
return r8asm_synth_run<5>(in, out, map, name, layout);
return r8asm_synth_run<5>(in, out, map, name, layout, mode);
case 6:
return r8asm_synth_run<6>(in, out, map, name, layout);
return r8asm_synth_run<6>(in, out, map, name, layout, mode);
case 7:
return r8asm_synth_run<7>(in, out, map, name, layout);
return r8asm_synth_run<7>(in, out, map, name, layout, mode);
default:
return r8asm_synth_run<8>(in, out, map, name, layout);
return r8asm_synth_run<8>(in, out, map, name, layout, mode);
}
}