Skip to content

Commit 3b8b1f1

Browse files
t81devt81dev
committed
Guided ternary examples
1 parent 1e8a8ec commit 3b8b1f1

13 files changed

Lines changed: 258 additions & 1 deletion

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,11 @@ __ternary_tb2t_t32 __ternary_tb2t_t64 __ternary_tb2t_t128 __ternary_tt2b_t32 __t
198198

199199
This inventory is the contract: any runtime or hardware backend must implement these symbols with the semantics described in `SPECIFICATION.md`.
200200

201+
## AI-focused examples
202+
203+
Progressively richer examples help a new user (or AI agent) understand how ternary source maps to the helper ABI. See [`docs/examples.md`](docs/examples.md) for a 10-step guided suite that links code snippets, plugin flags, and emitted helpers from simple selects up through TMUX/TNET routing and coverage diagnostics.
204+
Run `tools/quickstart.sh` to compile every example with the plugin and surface the Phase 3/4 diagnostics log automatically.
205+
201206
## Control Flow
202207

203208
Lowering focuses on making ternary control dependencies explicit in GIMPLE; actual binary branching encodings
@@ -234,4 +239,3 @@ See `examples/` for demo programs covering basic usage, calculator-style logic,
234239
## Contributing
235240

236241
See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines, coding standards, and how to run tests locally.
237-

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,4 @@ The repository README now lives at [`../README.md`](../README.md) so that visito
77
- [docs/SPECIFICATION.md](SPECIFICATION.md)
88
- [docs/MASTER_ISA.md](MASTER_ISA.md)
99
- [docs/ENCODING.md](ENCODING.md)
10+
- [`docs/examples.md`](examples.md) (guided sample programs + instructions to run `tools/quickstart.sh`)

‎docs/examples.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Guided ternary examples
2+
3+
The goal for these examples is to teach both humans and AI agents how the plugin lowers C/C++ to the helper ABI and what capabilities the ternary runtime exposes. Each example builds on the previous one, linking a code pattern to a helper set, plugin flags, and the roadmap phase it exercises.
4+
5+
| Tier | Example | Source | Plugin flags | Key helpers / semantics | Roadmap focus |
6+
|------|---------|--------|--------------|-------------------------|---------------|
7+
| 1 | **Hello ternary select** — write a ternary condition and select between two `int` values so new users see how `TERNARY_COND_T` flows into `__ternary_select_i32`. | `examples/example1_select.c` | `-fplugin-arg-ternary_plugin-lower` | `__ternary_create_cond` (implicit), `__ternary_select_i32` | Phase 0/2 (C surface) |
8+
| 2 | **Binary-to-ternary conversion** — call `__ternary_tb2t_t32`/`__ternary_tt2b_t32` plus `tb2t` literal helper to show how binary ints become packed trits and back. | `examples/example2_conversion.c` | `-fplugin-arg-ternary_plugin-conv` | `__ternary_tb2t_t32`, `__ternary_tt2b_t32`, `__ternary_bt_str_t32` | Phase 1 (runtime conversions) |
9+
| 3 | **Arithmetic chain** — add/mul/sub/muladd a few ternary values so the lowered helpers (`__ternary_add_t32`, `__ternary_mul_t32`, `__ternary_tmuladd_t32`) appear in sequence. | `examples/example3_arithmetic.c` | `-fplugin-arg-ternary_plugin-arith` | math helpers + `__ternary_tround_t32` for rounding | Phase 3 (lowering coverage) |
10+
| 4 | **Logic/min/max** — compute `tmin`, `tmax`, `tequiv`, `txor` on packed inputs to illustrate ternary logic semantics. | `examples/example4_logic.c` | `-fplugin-arg-ternary_plugin-logic` | `__ternary_tmin_t32`, `__ternary_tequiv_t32`, `__ternary_txor_t32` | Phase 3 |
11+
| 5 | **Conditional branch pipeline** — use `if (cond == 1)`, `else if` etc. to trigger `__ternary_tbranch` steps, showing how select/branch helpers pair with `tsignjmp`. | `examples/example5_branch.c` | `-fplugin-arg-ternary_plugin-lower -fplugin-arg-ternary_plugin-shift` | `__ternary_tbranch`, `__ternary_tsignjmp_t32`, `__ternary_shl_t32` | Phase 3/4 (control flow) |
12+
| 6 | **Vector arithmetic** — operate on `tv32_t` (or `tv64_t`) values so `__ternary_add_tv32`/`__ternary_cmp_tv32` appear; mention how the runtime currently folds them to scalar helpers. | `examples/example6_vector.c` | `-fplugin-arg-ternary_plugin-vector` | `__ternary_add_tv32`, `__ternary_cmp_tv32`, fallback to `__ternary_cmplt_t32` | Phase 7 (SIMD exploration) |
13+
| 7 | **Shift/rotate pipeline** — combine `__ternary_shl_t32`, `__ternary_shr_t32`, `__ternary_rol_t32`, `__ternary_ror_t32` to demonstrate trit-level shifts. | `examples/example7_shift.c` | `-fplugin-arg-ternary_plugin-shift` | shift/rotate helpers | Phase 4 (validation) |
14+
| 8 | **Memory load/store** — show how `t32_t` values persist through `__ternary_load_t32`/`__ternary_store_t32`, so the ABI matches binary-compatible storage. | `examples/example8_memory.c` | `-fplugin-arg-ternary_plugin-mem` | `__ternary_load_t32`, `__ternary_store_t32` | Phase 3 |
15+
| 9 | **TMUX/TNET routing** — an AI-relevant kernel that gathers three paths (neg/zero/pos) via `__ternary_tmux_t32` and summarizes with `__ternary_tnet_t32`. | `examples/example9_tmux.c` | `-fplugin-arg-ternary_plugin-logic -fplugin-arg-ternary_plugin-arith` | `__ternary_tmux_t32`, `__ternary_tnet_t32`, `__ternary_tequiv_t32` | Phase 4 (ternary-specific ISA) |
16+
| 10 | **Coverage-driven diagnostics** — run the quickstart script to build the above examples and capture the `tests/run_phase34_coverage.sh` trace log so AI/engineers know which helpers emit diagnostics. | `tools/quickstart.sh` | n/a (script) | coverage log, helper list audit (`tools/check_helper_docs.py`) | Phase 3/4 regression |
17+
18+
Each example should include a minimal C/C++ snippet (see `examples/`), the plugin command line, and the helpers it pushes into the runtime. Adding these to the documentation (and ideally as runnable snippets in `examples/`) helps both humans and agents understand the progression from simple selects to complex routing/diagnostics.

‎examples/example1_select.c‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#include <stdio.h>
2+
#include "ternary_runtime.h"
3+
4+
int main(void)
5+
{
6+
ternary_cond_t cond = __ternary_tt2b_t32(__ternary_tb2t_t32(1));
7+
int result_true = __ternary_select_i32(cond, 42, -42);
8+
9+
cond = __ternary_tt2b_t32(__ternary_tb2t_t32(0));
10+
int result_false = __ternary_select_i32(cond, 42, -42);
11+
12+
printf("select(true) -> %d\n", result_true);
13+
printf("select(false) -> %d\n", result_false);
14+
return 0;
15+
}

‎examples/example2_conversion.c‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#include <stdio.h>
2+
#include <inttypes.h>
3+
#include "ternary_runtime.h"
4+
5+
int main(void)
6+
{
7+
t32_t packed = __ternary_tb2t_t32(5);
8+
t32_t literal = __ternary_bt_str_t32("+1 0 -1 0 1");
9+
int64_t decoded = __ternary_tt2b_t32(packed);
10+
11+
printf("binary 5 -> packed (t32): %016" PRIX64 "\n", packed);
12+
printf("packed -> decoded: %" PRId64 "\n", decoded);
13+
printf("literal string -> decoded: %" PRId64 "\n", __ternary_tt2b_t32(literal));
14+
return 0;
15+
}

‎examples/example3_arithmetic.c‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#include <stdio.h>
2+
#include <inttypes.h>
3+
#include "ternary_runtime.h"
4+
5+
int main(void)
6+
{
7+
t32_t a = __ternary_tb2t_t32(2);
8+
t32_t b = __ternary_tb2t_t32(3);
9+
t32_t c = __ternary_tb2t_t32(-1);
10+
11+
t32_t sum = __ternary_add_t32(a, b);
12+
t32_t prod = __ternary_mul_t32(sum, b);
13+
t32_t fused = __ternary_tmuladd_t32(a, b, c);
14+
t32_t rounded = __ternary_tround_t32(prod, 1);
15+
16+
printf("sum=%" PRId64 "\n", __ternary_tt2b_t32(sum));
17+
printf("product=%" PRId64 "\n", __ternary_tt2b_t32(prod));
18+
printf("muladd=%" PRId64 "\n", __ternary_tt2b_t32(fused));
19+
printf("rounded(product)=%" PRId64 "\n", __ternary_tt2b_t32(rounded));
20+
return 0;
21+
}

‎examples/example4_logic.c‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
#include <stdio.h>
2+
#include <inttypes.h>
3+
#include "ternary_runtime.h"
4+
5+
int main(void)
6+
{
7+
t32_t mid = __ternary_tb2t_t32(0);
8+
t32_t up = __ternary_tb2t_t32(3);
9+
t32_t down = __ternary_tb2t_t32(-3);
10+
11+
t32_t tmin = __ternary_tmin_t32(up, down);
12+
t32_t tmax = __ternary_tmax_t32(up, mid);
13+
t32_t tequiv = __ternary_tequiv_t32(up, up);
14+
t32_t txor = __ternary_txor_t32(up, mid);
15+
16+
printf("tmin=%" PRId64 " tmax=%" PRId64 "\n", __ternary_tt2b_t32(tmin), __ternary_tt2b_t32(tmax));
17+
printf("tequiv=%" PRId64 " txor=%" PRId64 "\n", __ternary_tt2b_t32(tequiv), __ternary_tt2b_t32(txor));
18+
return 0;
19+
}

‎examples/example5_branch.c‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#include <stdio.h>
2+
#include "ternary_runtime.h"
3+
4+
int main(void)
5+
{
6+
ternary_cond_t cond_pos = __ternary_tt2b_t32(__ternary_tb2t_t32(1));
7+
ternary_cond_t cond_zero = __ternary_tt2b_t32(__ternary_tb2t_t32(0));
8+
t32_t shifted = __ternary_shl_t32(__ternary_tb2t_t32(2), 1);
9+
10+
int target_pos = __ternary_tbranch(cond_pos, -1, 0, 1);
11+
int target_zero = __ternary_tbranch(cond_zero, -1, 0, 1);
12+
int sjmp = __ternary_tsignjmp_t32(shifted, -5, 0, 5);
13+
14+
printf("branch(pos) target=%d\n", target_pos);
15+
printf("branch(zero) target=%d\n", target_zero);
16+
printf("signjmp(shifted) target=%d\n", sjmp);
17+
return 0;
18+
}

‎examples/example6_vector.c‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
#include <stdio.h>
2+
#include <inttypes.h>
3+
#include "ternary_runtime.h"
4+
5+
static inline tv32_t pack_tv32(t32_t lo, t32_t hi)
6+
{
7+
return (tv32_t)lo | ((tv32_t)hi << 64);
8+
}
9+
10+
static inline t32_t unpack_lo(tv32_t vec)
11+
{
12+
return (t32_t)(vec & 0xFFFFFFFFFFFFFFFFULL);
13+
}
14+
15+
static inline t32_t unpack_hi(tv32_t vec)
16+
{
17+
return (t32_t)(vec >> 64);
18+
}
19+
20+
int main(void)
21+
{
22+
t32_t lo = __ternary_tb2t_t32(2);
23+
t32_t hi = __ternary_tb2t_t32(-3);
24+
tv32_t vec_a = pack_tv32(lo, hi);
25+
tv32_t vec_b = pack_tv32(hi, lo);
26+
27+
tv32_t added = __ternary_add_tv32(vec_a, vec_b);
28+
tv32_t cmp = __ternary_cmp_tv32(vec_a, vec_b);
29+
30+
printf("add_lo=%" PRId64 " add_hi=%" PRId64 "\n",
31+
__ternary_tt2b_t32(unpack_lo(added)),
32+
__ternary_tt2b_t32(unpack_hi(added)));
33+
printf("cmp_lo=%" PRId64 " cmp_hi=%" PRId64 "\n",
34+
__ternary_tt2b_t32(unpack_lo(cmp)),
35+
__ternary_tt2b_t32(unpack_hi(cmp)));
36+
return 0;
37+
}

‎examples/example7_shift.c‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
#include <stdio.h>
2+
#include <inttypes.h>
3+
#include "ternary_runtime.h"
4+
5+
int main(void)
6+
{
7+
t32_t base = __ternary_tb2t_t32(5);
8+
t32_t left = __ternary_shl_t32(base, 1);
9+
t32_t right = __ternary_shr_t32(base, 1);
10+
t32_t rol = __ternary_rol_t32(base, 2);
11+
t32_t ror = __ternary_ror_t32(base, 2);
12+
13+
printf("shl=%" PRId64 " shr=%" PRId64 " rol=%" PRId64 " ror=%" PRId64 "\n",
14+
__ternary_tt2b_t32(left),
15+
__ternary_tt2b_t32(right),
16+
__ternary_tt2b_t32(rol),
17+
__ternary_tt2b_t32(ror));
18+
return 0;
19+
}

0 commit comments

Comments
 (0)