Skip to content

Commit fd2176a

Browse files
t81devt81dev
committed
examples
1 parent 3b8b1f1 commit fd2176a

1 file changed

Lines changed: 23 additions & 13 deletions

File tree

‎docs/examples.md‎

Lines changed: 23 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,28 @@
11
# Guided ternary examples
22

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.
3+
These examples are designed to be read top to bottom, one semantic step at a time. Each tier introduces exactly one new ternary concept, builds on the helper ABI from earlier tiers, and maps the pattern back to the roadmap phases described in `ROADMAP.md`. Agents and humans alike should treat the helper calls observed in the emitted code as the canonical representation of ternary semantics inside GCC.
44

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 |
5+
| Tier | Example | Source | Plugin flags | Key helpers / semantics | Roadmap focus | What to notice |
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_COND_T` value → `__ternary_select_i32` | Phase 0/2 (C surface) | Conditional semantics become data |
8+
| 2 | **Binary-to-ternary conversion** — call `__ternary_tb2t_t32`/`__ternary_tt2b_t32` plus the balanced-ternary string helper (`__ternary_bt_str_t32`) 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) | Binary ↔ ternary boundary is explicit |
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 | Phase 3 (lowering coverage) | Arithmetic lowers 1:1 to helpers |
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 | Logic operators stay ternary-aware |
11+
| 5 | **Conditional routing pipeline** — use `if / else if` ternary conditions to demonstrate how control intent is lowered into `__ternary_tbranch` / `__ternary_tsignjmp_*`, without yet emitting native branch instructions. | `examples/example5_branch.c` | `-fplugin-arg-ternary_plugin-lower -fplugin-arg-ternary_plugin-cmp -fplugin-arg-ternary_plugin-trace -fplugin-arg-ternary_plugin-dump-gimple` | `__ternary_cmp_t32`, `__ternary_tbranch`, `__ternary_tsignjmp_t32` | Phase 3/4 (control flow) | Control intent is reified w/out native branch |
12+
| 6 | **Vector arithmetic** — operate on `tv32_t` (or `tv64_t`) values so `__ternary_add_tv32`/`__ternary_cmp_tv32` appear; highlight how the runtime folds vector helpers to scalar `t32_t` helpers for correctness while the ABI stays the same. | `examples/example6_vector.c` | `-fplugin-arg-ternary_plugin-vector` | `__ternary_add_tv32`, `__ternary_cmp_tv32` | Phase 7 (SIMD exploration) | Vector helpers canonicalize to scalars |
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) | Trit-level updates stay consistent |
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 | ABI matches binary storage |
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) | Routing replaces boolean control |
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 | Diagnostics log is canonical |
1717

1818
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.
19+
20+
Every tier compiles with the same template so the emitted helpers can be compared deterministically:
21+
22+
```bash
23+
cc -Iinclude -fplugin=./ternary_plugin.so \
24+
<plugin-flags> examples/<name>.c runtime/ternary_runtime.c \
25+
-o build/examples/<name> && ./build/examples/<name>
26+
```
27+
28+
Add `-fplugin-arg-ternary_plugin-trace` and `-fplugin-arg-ternary_plugin-dump-gimple` when you want to capture traces or GIMPLE dumps that list the helper calls for inspection.

0 commit comments

Comments
 (0)