Bootstrap ternary plugin: types, lowering pass, runtime helpers

Author: t81dev

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
             gcc-version: 15
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
 
     - name: Install GCC ${{ matrix.gcc-version }}
       if: matrix.os == 'ubuntu-latest'
@@ -39,6 +39,20 @@ jobs:
         echo "CC=gcc-${{ matrix.gcc-version }}" >> $GITHUB_ENV
         echo "CXX=g++-${{ matrix.gcc-version }}" >> $GITHUB_ENV
 
+    - name: Build runtime
+      run: make runtime
+
+    - name: Build plugin
+      run: make plugin
+
     - name: Run Tests
+      run: make test
+
+    - name: Install
+      run: sudo make install
+
+    - name: Test installation
       run: |
-        make test
+        echo '#include <ternary.h>' > test_install.c
+        echo 'int main() { return 0; }' >> test_install.c
+        $CC -I/usr/local/include/ternary -c test_install.c -o test_install.o

CMakeLists.txt

@@ -15,13 +15,37 @@ if(NOT GCC_PLUGIN_INCLUDE_DIR)
     message(FATAL_ERROR "GCC plugin include directory not found")
 endif()
 
+# Find GMP
+find_path(GMP_INCLUDE_DIR
+    NAMES gmp.h
+    PATHS /opt/homebrew/include
+          /usr/include
+          /usr/local/include
+)
+
+if(NOT GMP_INCLUDE_DIR)
+    message(FATAL_ERROR "GMP include directory not found")
+endif()
+
+find_library(GMP_LIBRARY
+    NAMES gmp
+    PATHS /opt/homebrew/lib
+          /usr/lib
+          /usr/local/lib
+)
+
+if(NOT GMP_LIBRARY)
+    message(FATAL_ERROR "GMP library not found")
+endif()
+
 include_directories(${GCC_PLUGIN_INCLUDE_DIR})
+include_directories(${GMP_INCLUDE_DIR})
 include_directories(include)
 
 # Plugin
 add_library(ternary_plugin SHARED src/ternary_plugin.cpp)
 target_compile_definitions(ternary_plugin PRIVATE PIC)
-target_link_libraries(ternary_plugin -Wl,-undefined,dynamic_lookup)
+target_link_libraries(ternary_plugin ${GMP_LIBRARY} -Wl,-undefined,dynamic_lookup)
 
 # Runtime
 add_library(ternary_runtime STATIC runtime/ternary_runtime.c)

README.md

@@ -4,8 +4,10 @@ This is a GCC plugin and helper ABI for a balanced-ternary ISA. It analyzes tern
 expressions in C/C++ and can lower them to helper calls that map to ternary ISA
 instructions.
 
+**Note:** This project is a passion/research effort exploring ternary logic, which has theoretical advantages in arithmetic and AI contexts. It is currently at an early stage, compiling and running toy examples, rather than a mature toolchain component.
+
 The plugin supports:
-- Packed ternary types: `t6_t`, `t12_t`, `t24_t` (6, 12, 24 trits; 2-bit packed encoding)
+- Packed ternary types: `t32_t`, `t64_t`, `t128_t` (32/64/128 trits; 2-bit packed encoding)
 - Extended arithmetic operations: add, sub, mul, div, mod, neg
 - Logic operations: not
 - Comparison operations: cmp (returns -1, 0, +1)
@@ -19,10 +21,10 @@ described in `SPECIFICATION.md`.
 
 Balanced ternary offers symmetric range and simpler arithmetic compared to two's complement binary.
 
-| Aspect | Balanced Ternary (e.g., 12 trits, 24 bits) | Two's Complement (e.g., 24-bit int) |
-|--------|--------------------------------------------|-------------------------------------|
-| Range  | -531441 to 531441                          | -8388608 to 8388607                |
-| Dynamic Range | Higher for same bits (3^12 vs 2^24)     | Standard binary range              |
+| Aspect | Balanced Ternary (e.g., 32 trits, 64 bits) | Two's Complement (e.g., 64-bit int) |
+|--------|-------------------------------------------|-------------------------------------|
+| Range  | -926510094425920 to 926510094425920       | -9223372036854775808 to 9223372036854775807 |
+| Dynamic Range | 3^32 vs 2^64                        | Standard binary range              |
 | Rounding | Symmetric (no bias toward positive/negative) | Biased toward negative             |
 | Arithmetic Simplicity | Easier carry-free ops in hardware | Complex carry propagation          |
 
@@ -48,6 +50,8 @@ make install
 
 This installs to `/usr/local/lib` and `/usr/local/include/ternary` by default. Adjust `DESTDIR` if needed.
 
+**Note:** On macOS, Apple Clang does not support GCC plugins. Use Homebrew GCC (e.g., `gcc-14` or `gcc-15`) instead.
+
 ### macOS Users - Important!
 
 Apple Clang (even when invoked as `gcc`) does not support GCC plugins. You may
@@ -133,8 +137,8 @@ Optional arguments:
   `__builtin_ternary_shl`, `__builtin_ternary_shr`, `__builtin_ternary_rol`, and `__builtin_ternary_ror`.
 - `-fplugin-arg-ternary_plugin-conv` enables lowering of ternary conversion builtins like
   `__builtin_ternary_tb2t`, `__builtin_ternary_tt2b`, `__builtin_ternary_t2f`, and `__builtin_ternary_f2t`.
-- `-fplugin-arg-ternary_plugin-types` enables builtin ternary integer types `t6_t`, `t12_t`,
-  `t24_t`, `t48_t`, `t96_t`, `t192_t` with packed 2-bit trit storage.
+- `-fplugin-arg-ternary_plugin-types` enables builtin ternary integer types `t32_t`, `t64_t`,
+  `t128_t` with packed 2-bit trit storage.
 - `-fplugin-arg-ternary_plugin-prefix=<name>` sets the function name prefix used by `-lower`
   (default: `__ternary_select`).
 
@@ -161,8 +165,9 @@ For testing without the plugin, the header provides C implementations of all ter
 Packed ternary types use a 2-bit encoding per trit (00 = -1, 01 = 0, 10 = +1).
 Define `TERNARY_USE_BUILTIN_TYPES` before including the header when compiling with
 `-fplugin-arg-ternary_plugin-types` to avoid typedef conflicts.
-Helper/runtime support is currently provided for t6/t12/t24 only; t48/t96/t192 require
-custom runtime implementations.
+Helper/runtime support is currently provided for t32/t64 only; t128 requires
+custom runtime implementations. The reference runtime uses 64-bit logical
+conversion helpers, so t64 correctness is limited to values that fit in int64.
 
 For example:
 
@@ -185,15 +190,48 @@ gcc -fplugin=./ternary_plugin.so -fplugin-arg-ternary_plugin-lower -Iinclude -c
 
 For a minimal out-of-line runtime, use the reference implementation in `runtime/ternary_runtime.c`
 with the public header `include/ternary_runtime.h`. It implements the same packed 2-bit-trit
-semantics as the helpers (t6/t12/t24) and is intended as a starting point for a real ISA-backed
-library. Packed helpers for t48/t96/t192 are not provided in this reference runtime.
+semantics as the helpers (t32/t64) and is intended as a starting point for a real ISA-backed
+library. Packed helpers for t128 are not provided in this reference runtime.
 
 Example build:
 
 ```bash
 cc -Iinclude -c runtime/ternary_runtime.c -o ternary_runtime.o
 ```
 
+The `runtime_skeleton/` directory includes a tiny standalone helper set plus a sanity-check
+test you can build and run:
+
+```bash
+mkdir -p build
+cc -Iruntime_skeleton/include runtime_skeleton/src/ternary_runtime_skeleton.c \
+  runtime_skeleton/test_runtime_skeleton.c -o build/runtime_skeleton_test
+./build/runtime_skeleton_test
+```
+
+## Godbolt Recipe (Local-Equivalent)
+
+Godbolt does not allow custom GCC plugins, so use the local equivalent command line to reproduce
+what you would run in Compiler Explorer with a plugin-enabled GCC build:
+
+```bash
+cc -fplugin=./ternary_plugin.so \
+  -fplugin-arg-ternary_plugin-types \
+  -fplugin-arg-ternary_plugin-lower \
+  -fplugin-arg-ternary_plugin-arith \
+  -fplugin-arg-ternary_plugin-logic \
+  -fplugin-arg-ternary_plugin-cmp \
+  -fplugin-arg-ternary_plugin-shift \
+  -fplugin-arg-ternary_plugin-conv \
+  -Iinclude -c examples/ternary_basic.c -o build/ternary_basic.o
+```
+
+Link with the reference runtime object to satisfy helper symbols:
+
+```bash
+cc build/ternary_basic.o runtime/ternary_runtime.o -o build/ternary_basic
+```
+
 ## Testing
 
 Use the provided test file:
@@ -216,12 +254,23 @@ make test CXX=g++-15 CC=gcc-15
 This plugin analyzes ternary conditional expressions in the code and can optionally
 lower ternary operations to helper calls suitable for targeting a balanced-ternary ISA.
 
+## Balanced Ternary Literals
+
+Use balanced-ternary strings to construct packed values:
+
+```c
+t32_t a = T32_BT_STR("1 0 -1 1");
+t64_t b = T64_BT_STR("1,0,0,-1");
+```
+
+The parser consumes trits from left to right (most significant to least significant).
+
 ## Known Limitations
 
 - No auto-vectorization for ternary operations yet.
 - Performance is reference implementation; optimized ternary hardware would excel.
 - Limited interaction testing with GCC optimizations (-O3 may affect lowering).
-- No support for ternary literals or advanced syntax beyond builtins.
+- No native literal syntax; use the balanced-ternary string macros.
 - Plugin requires GCC with plugin support (not available in all distributions).
 
 ## Examples

SPECIFICATION.md

@@ -51,19 +51,32 @@ reinterpretation of the same trit pattern with a different comparison rule.
 
 The ISA defines ternary integer types by trit width:
 
-- t6, t12, t24, t48, t96, t192 (suggested), with platform-specific availability.
+- t32, t64, t128 (initial focus), with platform-specific availability.
 
 The toolchain maps these to C integer types via a storage ABI that packs trits into
 binary containers. A recommended mapping using 2-bit trit packing is:
 
-- t6  -> stored in 16-bit container (12 bits used)
-- t12 -> stored in 32-bit container (24 bits used)
-- t24 -> stored in 64-bit container (48 bits used)
-- t48 -> stored in 128-bit container (96 bits used)
+- t32  -> stored in 64-bit container
+- t64  -> stored in 128-bit container
+- t128 -> stored in 256-bit container
 
 Packing is logical; the physical encoding is an ABI detail. Compilers must preserve
 bit patterns across loads/stores and calls.
 
+### Source Literal Helpers
+
+The current toolchain does not define a native ternary literal token. Instead, it
+provides helpers that parse balanced-ternary strings left-to-right (most significant
+trit first). Example:
+
+```c
+t32_t a = T32_BT_STR("1 0 -1 1");
+t64_t b = T64_BT_STR("1,0,0,-1");
+```
+
+The runtime parser accepts `-1`, `0`, `1`, or `+1` tokens separated by whitespace or
+commas. Invalid strings return zero.
+
 ### Boolean and Condition Types
 
 Condition values are trits. Comparisons produce {-1, 0, +1}. Branches and selects
@@ -77,6 +90,15 @@ decoded with tt2b first.
 IEEE-754 binary float and double are preserved. Ternary select supports floats, but
 ternary arithmetic is limited to integer types for now.
 
+### Type Promotion and Conversion Rules
+
+Ternary types follow C-like promotion rules for operations:
+
+- Usual arithmetic conversions: smaller types promote to larger (t32 -> t64 -> t128).
+- Mixed ternary/binary: ternary promotes to binary container size for compatibility.
+- Condition handling: ternary conditions are ternary_cond_t (int8_t with trit values).
+- Conversions: explicit casts use helper functions; implicit conversions require plugin lowering.
+
 ## Instruction Semantics
 
 ### Arithmetic
@@ -90,10 +112,9 @@ Ternary logic is defined with min/max semantics:
 
 - tand(a,b) = min(a,b)
 - tor(a,b)  = max(a,b)
-- txor(a,b) = a + b - 2 * min(a,b) - 2 * max(a,b) (ISA may choose alternative ternary XOR)
+- txor(a,b) = 0 if a == b, else -a if b == 0, else -b if a == 0, else 0
 
-Implementations may choose a different ternary XOR definition, but it must be
-documented and stable.
+This definition is stable and documented.
 
 ### Comparisons
 
@@ -176,8 +197,8 @@ but operand formats and semantics are fully specified. The ISA operates on packe
 - Fn: IEEE floating-point register (f32/f64).
 - Imm: immediate value (binary-encoded).
 
-Ternary registers have a fixed trit width per instruction variant (e.g., t6, t12,
-t24, t48, t96, t192). The width is encoded in the mnemonic suffix.
+Ternary registers have a fixed trit width per instruction variant (e.g., t32, t64,
+t128). The width is encoded in the mnemonic suffix.
 
 ### Register and Instruction Formats
 
@@ -190,6 +211,18 @@ The base ISA assumes a three-operand format for ternary ALU operations:
 
 Where:
 - Td/Ta/Tb/Tc are ternary registers of width tN.
+
+## Roadmap / Next Steps
+
+Priority | Suggestion | Why it helps | Status
+--- | --- | --- | ---
+High | Finish/clean lowering for common ops (add/sub/mul/neg/cmp/select/conv) | Lets users write straightforward ternary arithmetic without manual loops | In progress
+High | Small portable runtime lib for t32/t64 | Enables real programs and benchmarking | Implemented (reference runtime in `runtime/`)
+Medium | Trit-count-aware constant folding in plugin | Allows constants like `t32_t x = 42` to fold when representable | In progress
+Medium | Better ternary type creation and user-facing syntax (e.g., `__ternary(32)` or attributes) | Easier adoption | Planned
+Medium | Dump stats on how many ternary ops survive to RTL/assembly | Quantifies remaining work for hardware targets | Planned
+Low | Larger trit counts (t256+) via limb-based runtime emulation | Future-proofs larger types | Planned
+Low | Branch-free ternary↔binary conversion helpers | Improves emulation speed | Planned
 - Rd is a binary integer register holding {-1,0,+1} in two's complement.
 
 ### Instruction Semantics
@@ -311,6 +344,12 @@ macros to decode promotions for packed ternary types.
 - __builtin_ternary_or(a, b)
 - __builtin_ternary_xor(a, b)
 - __builtin_ternary_cmp(a, b)
+- __builtin_ternary_eq(a, b) -> int
+- __builtin_ternary_ne(a, b) -> int
+- __builtin_ternary_lt(a, b) -> int
+- __builtin_ternary_le(a, b) -> int
+- __builtin_ternary_gt(a, b) -> int
+- __builtin_ternary_ge(a, b) -> int
 - __builtin_ternary_shl(a, b)
 - __builtin_ternary_shr(a, b)
 - __builtin_ternary_rol(a, b)
@@ -323,7 +362,7 @@ macros to decode promotions for packed ternary types.
 ### Custom Types
 
 When `-fplugin-arg-ternary_plugin-types` is enabled, the plugin registers builtin
-types `t6_t`, `t12_t`, `t24_t`, `t48_t`, `t96_t`, and `t192_t` with packed 2-bit
+types `t32_t`, `t64_t`, and `t128_t` with packed 2-bit
 trit storage (precision = trit_count * 2).
 
 ### Helper ABI
@@ -344,6 +383,12 @@ Helper functions implement ISA-visible operations in C:
 - __ternary_or(a, b)
 - __ternary_xor(a, b)
 - __ternary_cmp(a, b)
+- __ternary_eq(a, b) -> int
+- __ternary_ne(a, b) -> int
+- __ternary_lt(a, b) -> int
+- __ternary_le(a, b) -> int
+- __ternary_gt(a, b) -> int
+- __ternary_ge(a, b) -> int
 - __ternary_shl(a, b)
 - __ternary_shr(a, b)
 - __ternary_rol(a, b)
@@ -366,7 +411,7 @@ ternary_cond_t before calling helpers. The reference helper header uses a packed
 
 ## Testing and Validation
 
-- Ternary select: int, unsigned, float, double, and custom ternary types (t6_t, t12_t, t24_t).
+- Ternary select: int, unsigned, float, double, and custom ternary types (t32_t, t64_t).
 - Arithmetic builtins: add, sub, mul, div, mod, neg.
 - Logic builtins: not.
 - Comparison builtins: cmp (returns -1, 0, +1).
@@ -384,14 +429,14 @@ ternary_cond_t before calling helpers. The reference helper header uses a packed
 - Comparison builtin lowering (cmp)
 - Helper function ABI with packed C implementations for testing
 - Test suite covering all implemented operations
-- Builtin ternary type registration (t6_t, t12_t, t24_t, t48_t, t96_t, t192_t)
-- Shift/rotate builtin lowering (t6/t12/t24)
+- Builtin ternary type registration (t32_t, t64_t, t128_t)
+- Shift/rotate builtin lowering (t32/t64)
 - Conversion builtin lowering (tb2t, tt2b, t2f, f2t)
 
 ### Known Limitations
 - GCC 15 API compatibility may still require adjustments
-- Packed ternary helpers currently cover t6/t12/t24 only (no big-int support for t48+)
-- Reference runtime/helpers do not implement t48/t96/t192 operations
+- Packed ternary helpers currently cover t32/t64 only (no big-int support for t128)
+- Reference runtime/helpers do not implement t128 operations
 
 ## Future Extensions
 
@@ -406,9 +451,9 @@ ternary_cond_t before calling helpers. The reference helper header uses a packed
 ## Still Needs Implementation
 
 1. Custom ternary types
-   - Implemented: builtin types t6, t12, t24, t48, t96, t192 (packed 2-bit trits)
+   - Implemented: builtin types t32, t64, t128 (packed 2-bit trits)
    - Implemented: storage ABI for 2-bit trit packing
-   - Remaining: helper/runtime support for t48/t96/t192 (requires big-int support)
+   - Remaining: helper/runtime support for t128 (requires big-int support)
 2. Extended arithmetic operations
    - Implemented: tsub, tdiv, tmod, tneg builtins and helpers
    - Remaining: validation coverage for edge cases and larger widths
@@ -419,10 +464,10 @@ ternary_cond_t before calling helpers. The reference helper header uses a packed
    - Implemented: tcmp builtins and helpers (-1/0/+1)
    - Remaining: validation coverage for edge cases and larger widths
 5. Shifts and rotates
-   - Implemented: trit-based shl/shr/rol/ror builtins and helpers (t6/t12/t24)
+   - Implemented: trit-based shl/shr/rol/ror builtins and helpers (t32/t64)
    - Remaining: validation coverage and larger width support
 6. Type conversions
-   - Implemented: tb2t/tt2b and t2f/f2t builtins and helpers (t6/t12/t24)
+   - Implemented: tb2t/tt2b and t2f/f2t builtins and helpers (t32/t64)
    - Remaining: precise rounding semantics for larger widths
 7. Full ISA integration
    - Missing: Complete mapping to all specified ISA instructions
@@ -433,6 +478,6 @@ ternary_cond_t before calling helpers. The reference helper header uses a packed
 
 ## Priority Order
 
-- High: Helper support for larger ternary widths (t48/t96/t192)
+- High: Helper support for larger ternary widths (t128)
 - Medium: Varargs ABI validation tests for ternary types
 - Low: Optional hardware ISA support for ternary mnemonics